이 가이드는 API 명세를 기반으로 AI가 자동 생성했습니다.
Classic/VPC 환경에서 이용 가능합니다.
Ncloud 표준 표현을 적용한 API입니다.
Ncloud Single Sign-On은 하나의 계정으로 다양한 애플리케이션에 접속할 수 있는 시스템을 구축하는 네이버 클라우드 플랫폼의 서비스입니다.
Ncloud Single Sign-On 서비스에서는 Application, Tenant, External IdP, SSO User, 그룹, Permission Set, Assignment, IP ACL 기능에 대한 API를 RESTful 형태로 제공합니다.
참고
API의 가독성을 높이기 위해 Ncloud Single Sign-On API의 v1 버전을 ncloud에서 정의한 표준 표현에 의거하여 v2 버전으로 새롭게 출시하였습니다.
Ncloud Single Sign-On 요청 형식
Ncloud Single Sign-On API에서 공통으로 사용하는 요청 형식을 설명합니다.
API URL
요청 API URL은 다음과 같습니다.
https://sso.apigw.ntruss.com/api/v2
요청 헤더
요청 헤더에 대한 설명은 다음과 같습니다.
| 필드 | 필수 여부 | 설명 |
|---|---|---|
x-ncp-apigw-timestamp |
Required | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간(밀리초)
|
x-ncp-iam-access-key |
Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key
|
x-ncp-apigw-signature-v2 |
Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명
|
Ncloud Single Sign-On 응답 형식
Ncloud Single Sign-On API에서 공통으로 사용하는 응답 형식을 설명합니다.
응답 바디
API 오류 시 공통으로 반환하는 응답 바디는 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
error |
Object<ErrorDetail> | - | 에러 정보 |
ErrorDetail
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
errorCode |
String | - | 에러 코드
|
message |
String | - | 에러 메시지
|
detail |
String | - | 에러 상세 정보
|
fieldErrors |
List<FieldError> | - | 입력값 에러 상세 목록 |
FieldError
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
field |
String | - | 에러가 발생한 필드명
|
message |
String | - | 필드 에러 메시지
|
동기 방식 배치 API는 오류를 error와 failures 두 가지 중 하나의 형태로 응답합니다. 요청 항목과 무관한 오류(인증·권한, 요청 형식, 서버 내부 오류 등)는 error로, 요청 항목의 처리에서 발생한 실패는 failures로 반환합니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
error |
Object<ErrorDetail> | - | 에러 정보. 요청 항목과 무관한 오류(Tenant 미존재 등)에 사용 |
failures |
Map<BatchFailure> | - | 처리 실패 항목. 키는 요청 인덱스("0", "1", ...) |
failures.{index} |
Object<BatchFailure> | - |
BatchFailure
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
errorCode |
String | - | 에러 코드
|
message |
String | - | 에러 메시지
|
detail |
String | - | 에러 상세 정보
|
응답 상태 코드
응답 상태 코드에 대한 설명은 다음과 같습니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 200 | - | - | 각 API 문서의 응답 상태 코드를 참조 |
| 201 | - | - | 각 API 문서의 응답 상태 코드를 참조 |
| 204 | - | - | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | BadRequest | The request is malformed or contains an error such as an invalid parameter value or a missing required parameter. | 요청 본문 형식 오류 또는 필수 입력값 누락 |
| 400 | InvalidParameter | The specified parameter is invalid. | 입력값 형식 오류, 일치하지 않는 Assignment Target 입력, 배치 요청 항목 간 아이디 중복 |
| 400 | ResourceLimitExceeded | The request exceeds the resource limit. | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | InvalidCertificateFormat | The specified certificate format is invalid. | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | TagLimitExceeded | The maximum allowed number of tags was exceeded. | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | AlreadyExists | The resource with the name requested already exists. | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | InvalidState | Indicates that the specified state is not a valid state for an event source. | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | InvalidMetadataFormat | The specified metadata format is invalid. | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | InvalidConfiguration | Some or all of the configuration is incomplete, missing, or not valid. | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | CannotDelete | Indicates that the delete operation could not be completed. | 각 API 문서의 응답 상태 코드를 참조 |
| 401 | Unauthorized | Invalid authentication credentials. | 요청 헤더의 인증 정보(Access Key·서명·타임스탬프)가 없거나 유효하지 않은 경우 |
| 403 | AccessDenied | The client is permanently forbidden from making the request. | 호출 권한(액션)이 없는 서브 계정의 요청 |
| 403 | Forbidden | You do not have sufficient permissions to perform this action. | 마스터 계정이 아닌 계정으로 Organization 연동 요청 |
| 404 | NotFound | One or more of the resources in the request does not exist in the system. | 각 API 문서의 응답 상태 코드를 참조 |
| 404 | ResourceNotFound | The specified resource could not be found. | 각 API 문서의 응답 상태 코드를 참조 |
| 404 | UserNotFound | The specified user could not be found. | 각 API 문서의 응답 상태 코드를 참조 |
| 404 | PermissionSetNotFound | The specified permission set could not be found. | 각 API 문서의 응답 상태 코드를 참조 |
| 404 | IpAclNotFound | The specified ip acl could not be found. | 각 API 문서의 응답 상태 코드를 참조 |
| 404 | GroupNotFound | The specified group could not be found. | 각 API 문서의 응답 상태 코드를 참조 |
| 404 | AssignmentNotFound | The specified assignment could not be found. | 각 API 문서의 응답 상태 코드를 참조 |
| 404 | ApplicationNotFound | The specified application could not be found. | 각 API 문서의 응답 상태 코드를 참조 |
| 409 | AlreadyExists | The resource with the name requested already exists. | 각 API 문서의 응답 상태 코드를 참조 |
| 409 | ResourceInUse | The specified resource is in use. | 각 API 문서의 응답 상태 코드를 참조 |
| 409 | Conflict | The request could not be processed because of a conflict in the current status of the resource. | 각 API 문서의 응답 상태 코드를 참조 |
| 500 | InternalServerError | The request processing has failed because of an unknown error, exception, or failure. | 요청 처리 중 서버 내부 오류가 발생한 경우. 잠시 후 다시 요청 |
참고
네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Ncloud API 응답 상태 코드를 참조해 주십시오.
Ncloud Single Sign-On API
Ncloud Single Sign-On 서비스에서 제공하는 API에 대한 설명은 다음과 같습니다.
Application
Application 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createApplication | Application 생성 |
| getApplication | Application 단건 상세 조회 |
| listApplicationTags | Application에 추가한 태그 조회 |
| listApplications | Application 목록 조회 |
| updateApplication | Application 정보 수정 |
| deleteApplication | Application 삭제 |
| addApplicationTags | Application에 태그 추가 |
| removeApplicationTags | Application에 추가한 태그 삭제 |
| renewApplicationOauth2Secret | OAuth 2.0 Client Secret 재발급 |
Tenant
Tenant 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| getLoginSetting | Tenant 로그인 설정 조회 |
| getOrganization | Organization 연동 설정 조회 |
| getTenant | Tenant 조회 |
| listTenantTags | Tenant에 추가한 태그 조회 |
| updateLoginSetting | Tenant 로그인 설정 수정 |
| updateOrganization | Organization 연동 설정 수정 |
| updateTenant | Tenant 정보 수정 |
| addTenantTags | Tenant에 태그 추가 |
| removeTenantTags | Tenant에 추가한 태그 삭제 |
| subscribeTenant | Tenant 생성 |
| unsubscribeTenant | Tenant 삭제 |
External IdP
External IdP 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createIdpCertificate | IDP 인증서 등록 |
| createSamlIdp | External IdP 생성 |
| createSpCertificate | SP 인증서 등록 |
| getIdpCertificate | IDP 인증서 조회 |
| getIdpCertificateNotification | IDP 인증서 알림 조회 |
| getProfileMapping | Attribute Mapper 조회 |
| getSamlIdp | External IdP 조회 |
| getSpCertificate | SP 인증서 조회 |
| getSpCertificateNotification | SP 인증서 알림 조회 |
| getSpCertificatePem | SP 인증서 PEM 조회 |
| getSpData | Ncloud Single Sign-On URL 데이터 조회 |
| getSpMetadata | Ncloud Single Sign-On 메타데이터 조회 |
| listIdpCertificates | IDP 인증서 목록 조회 |
| listNotificationRecipientGroups | 통보 대상 그룹 목록 조회 |
| listNotificationRecipients | 통보 대상자 목록 조회 |
| listSamlIdps | External IdP 목록 조회 |
| listSpCertificates | SP 인증서 목록 조회 |
| updateIdpCertificateNotification | IDP 인증서 알림 설정 |
| updateProfileMapping | Attribute Mapper 수정 |
| updateSamlIdp | External IdP 정보 수정 |
| updateSpCertificateNotification | SP 인증서 알림 설정 |
| deleteIdpCertificate | IDP 인증서 삭제 |
| deleteSamlIdp | External IdP 삭제 |
| deleteSpCertificate | SP 인증서 삭제 |
| activateSpCertificate | SP 인증서 활성화 |
| parseSamlIdpMetadata | External IdP 메타데이터 파싱 |
SSO User
SSO User 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createUser | SSO User 단건 생성 |
| getUser | SSO User 단건 상세 조회 |
| getUserAccessRule | SSO User 접근 규칙 조회 |
| getUserGroup | SSO User가 속한 그룹 단건 상세 조회 |
| getUserMfaDevice | SSO User가 소유한 MFA Device 조회 |
| getUserProfile | SSO User Profile 조회 |
| listUserAssignments | SSO User가 속한 Assignment 목록 조회 |
| listUserGroups | SSO User가 속한 그룹 목록 조회 |
| listUserSessions | SSO User 세션 조회 |
| listUserTags | SSO User에 추가한 태그 조회 |
| listUsers | SSO User 목록 조회 |
| updateUser | SSO User 정보 수정 |
| updateUserAccessRule | SSO User 접근 규칙 수정 |
| deleteUser | SSO User 삭제 |
| addGroupsToUser | SSO User를 그룹에 추가 |
| addUserMfaDevice | SSO User에 MFA Device 추가 |
| addUserTags | SSO User에 태그 추가 |
| batchCreateUsers | SSO User 일괄 생성 |
| batchDeleteUsers | SSO User 일괄 삭제 |
| batchDisableUsers | SSO User 일괄 비활성화 |
| batchEnableUsers | SSO User 일괄 활성화 |
| batchExpireUserSessions | SSO User 세션 만료 |
| checkUserLoginId | SSO User 로그인 아이디 유효성 및 중복 여부 확인 |
| removeAssignmentsFromUser | SSO User를 Assignment에서 삭제 |
| removeGroupsFromUser | SSO User를 그룹에서 삭제 |
| removeUserMfaDevice | SSO User가 소유한 MFA Device 삭제 |
| removeUserTags | SSO User에 추가한 태그 삭제 |
Group
Group 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createGroup | 그룹 생성 |
| getGroup | 그룹 단건 상세 조회 |
| listGroupAssignments | 그룹이 속한 Assignment 목록 조회 |
| listGroupTags | 그룹에 추가한 태그 조회 |
| listGroupUsers | 그룹에 속한 SSO User 목록 조회 |
| listGroups | 그룹 목록 조회 |
| updateGroup | 그룹 정보 수정 |
| deleteGroup | 그룹 삭제 |
| addGroupTags | 그룹에 태그 추가 |
| addUsersToGroup | 그룹에 SSO User 추가 |
| batchDeleteGroups | 그룹 일괄 삭제 |
| checkGroupName | 그룹 이름 유효성 및 중복 여부 확인 |
| removeAssignmentsFromGroup | 그룹을 Assignment에서 삭제 |
| removeGroupTags | 그룹에 추가한 태그 삭제 |
| removeUsersFromGroup | 그룹에서 SSO User 삭제 |
Permission Set
Permission Set 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createPermissionSet | Permission Set 생성 |
| getPermissionSet | Permission Set 단건 상세 조회 |
| listManagedPolicies | Permission Set에 할당할 수 있는 관리형 정책(System Managed) 목록 조회 |
| listPermissionSetTags | Permission Set에 추가한 태그 조회 |
| listPermissionSets | Permission Set 목록 조회 |
| updatePermissionSet | Permission Set 정보 수정 |
| deletePermissionSet | Permission Set 삭제 |
| addPermissionSetTags | Permission Set에 태그 추가 |
| batchDeletePermissionSets | Permission Set 일괄 삭제 |
| checkPermissionSetName | Permission Set 이름 유효성 및 중복 여부 확인 |
| checkPermissionSetPolicyExists | Assignment 된 계정의 사용자 정의 정책(User Created) 존재 여부 확인 |
| removePermissionSetPolicies | Permission Set에 할당된 정책 삭제 |
| removePermissionSetTags | Permission Set에 추가한 태그 삭제 |
Assignment
Assignment 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createAssignment | Assignment 생성 |
| getAssignment | Assignment 단건 상세 조회 |
| listAssignmentIpAcls | Assignment에 추가된 IP ACL 목록 조회 |
| listAssignmentTags | Assignment에 추가한 태그 조회 |
| listAssignmentTargets | Assignment에 추가된 타깃(SSO User, 그룹) 목록 조회 |
| listAssignments | Assignment 목록 조회 |
| listOrganizationAccounts | Assignment에 추가할 수 있는 Organization 계정 목록 조회 |
| updateAssignment | Assignment 정보 수정 |
| deleteAssignment | Assignment 삭제 |
| addAssignmentTags | Assignment에 태그 추가 |
| addIpAclsToAssignment | Assignment에 IP ACL 추가 |
| addTargetsToAssignment | Assignment에 타깃(SSO User, 그룹) 추가 |
| changeAssignmentStatus | Assignment 활성화 또는 비활성화 설정 |
| checkAssignmentPolicyExists | 대상 계정 내 사용자 정의 정책(User Created) 존재 여부 확인 |
| removeAssignmentTags | Assignment에 추가한 태그 삭제 |
| removeIpAclsFromAssignment | Assignment에 추가된 IP ACL 삭제 |
| removeTargetsFromAssignment | Assignment에서 타깃(SSO User, 그룹) 삭제 |
IP ACL
IP ACL 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createIpAcl | IP ACL 생성 |
| getIpAcl | IP ACL 단건 상세 조회 |
| listIpAclAssignments | IP ACL에 추가된 Assignment 목록 조회 |
| listIpAclTags | IP ACL에 추가한 태그 조회 |
| listIpAcls | IP ACL 목록 조회 |
| updateIpAcl | IP ACL 정보 수정 |
| deleteIpAcl | IP ACL 삭제 |
| addAssignmentsToIpAcl | IP ACL에 Assignment 추가 |
| addIpAclTags | IP ACL에 태그 추가 |
| batchDeleteIpAcls | IP ACL 일괄 삭제 |
| removeAssignmentsFromIpAcl | IP ACL에서 Assignment 삭제 |
| removeIpAclTags | IP ACL에 추가한 태그 삭제 |
Ncloud Single Sign-On 연관 콘텐츠
Ncloud Single Sign-On API에 대한 사용자의 이해를 돕기 위해 다양한 연관 콘텐츠를 제공하고 있습니다.
-
Ncloud Single Sign-On API 사용 방법
- API 개요: 네이버 클라우드 플랫폼에서 발급받은 Access Key, Secret Key 발급 및 확인, 요청 헤더에 필요한 서명 생성 방법
- Sub Account 사용 가이드: 서브 계정의 Access Key 발급 및 확인 방법
- API Gateway 사용 가이드: 요청 헤더에 필요한 API Key 확인 방법
-
Ncloud Single Sign-On 서비스 사용 방법
- Ncloud Single Sign-On 사용 가이드: 네이버 클라우드 플랫폼 콘솔에서 Ncloud Single Sign-On 사용하는 방법
- Ncloud 사용 환경 가이드: VPC, Classic 환경 및 지원 여부에 대한 가이드
- 요금 소개, 특징, 상세 기능: Ncloud Single Sign-On의 요금 체계, 특징, 상세 기능 요약
- 서비스 최신 소식: Ncloud Single Sign-On 관련 최신 소식
- 자주 하는 질문: Ncloud Single Sign-On 사용자들이 자주 하는 질문
- 문의하기: 사용 가이드를 통해서도 궁금증이 해결되지 않는 경우 직접 문의