Application 연동 API

등록한 Application을 Ncloud Single Sign-On에 연동하는 방법을 설명합니다. 연동은 Ncloud Single Sign-On에서 제공하는 연동 API를 통해 진행합니다. Ncloud Single Sign-On 연동 API가 제공하는 기능은 다음과 같습니다.

• 권한 부여
• Token 발급
• Token 취소
• 인증된 사용자의 클레임 반환
• ID Token 서명 키 반환

권한 부여

Resource Owner와 상호 작용하고 보호된 리소스에 접근하는 권한을 부여받기 위해 필요한 API를 설명합니다.

요청

Client가 보호된 리소스에 접근할 수 있도록 IDP에 보내는 요청은 다음과 같습니다.

GET /tenants/{Tenant Id or Alias}/oauth2/authorize

• 요청 Path

  파라미터명	타입	필수 여부	제약 사항	설명
  Tenant Id or Alias	String	필수	-	Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias

• 요청 파라미터

  파라미터명	타입	필수 여부	제약 사항	설명
  response_type	String	필수	code 또는 token	Authorization Code 또는 Implicit 플로우 진행 시 필요한 값
  client_id	String	필수	-	Application 등록 시 발급받은 Client ID
  redirect_uri	String	필수	Application 등록 시 입력한 Redirect URI와 반드시 일치	권한 부여 완료 후 이동하게 되는 페이지의 URL
  scope	String	필수	-	접근 가능 범위. 추가 범위를 요청하기 위해서는 하나 이상의 범위 값을 공백으로 구분하여 포함.
  state	String	선택	-	CSRF 방어를 위한 임의의 값. state 권한 부여 완료 후 state를 포함해 redirect_uri에 입력한 페이지로 이동
  code_challenge	String	선택	Access Type이 public일 경우 사용	PKCE 적용 시 필요한 Code Challenge의 값
  code_challenge_method	String	선택	Access Type이 public일 경우 사용, plain 또는 S256	PKCE 적용 시 필요한 Code Challenge Method의 값

예시는 다음과 같습니다.

• response_type이 code인 경우

  GET /tenants/{Tenant Id or Alias}/oauth2/authorize?client_id=${Client Id}&scope=${Scope}&response_type=code&redirect_uri=${Redirect URI}&state=${State} HTTP/1.1
  Host: sso.ncloud.com
  

• code_challenge 및 code_challenge_method를 추가하여 권한 부여를 요청한 경우

  GET /tenants/{Tenant Id or Alias}/oauth2/authorize?client_id=${Client Id}&scope=${Scope}&response_type=code&redirect_uri=${Redirect URI}&state=${State}&code_challenge=${Code Challenge}&code_challenge_method=${Code Challenge Method} HTTP/1.1
  Host: sso.ncloud.com
  

• response_type이 token인 경우

  GET /tenants/{Tenant Id or Alias}/oauth2/authorize?client_id=${Client Id}&scope=${Scope}&response_type=token&redirect_uri=${Redirect URI}&state=${State} HTTP/1.1
  Host: sso.ncloud.com
  

응답

요청에 대한 응답은 다음과 같습니다.

• response_type이 code인 경우

  HTTP/1.1 302 Found
  Location: {Redirect URI}
  ?code=${Authorization code}
  &state=${State}
  

  파라미터명	타입	필수 여부	제약 사항	설명
  redirect_uri	String	필수	요청 시 포함한 redirect_uri	권한 부여 완료 후 이동하게 되는 페이지의 URL
  code	String	필수	유출 위험을 방지하기 위해 1분 후 만료	IDP에서 생성한 Authorization code
  state	String	선택	-	Client가 요청한 값

• response_type이 token인 경우

  HTTP/1.1 302 Found
  Location: {Redirect URI}
  ?access_token={Access Token}
  &token_type=Bearer
  &expires_in={Access Token Expire Date}
  &state={State}
  

  파라미터명	타입	필수 여부	제약 사항	설명
  redirect_uri	String	필수	요청 시 포함한 redirect_uri	권한 부여 완료 후 이동하게 되는 페이지의 URL
  access_token	String	필수	-	권한이 부여된 Access Token
  expires_in	Number	필수	-	Access Token의 유효 기간
  state	String	선택	-	Client가 요청한 값

Token 발급

접근 권한이 부여된 후 자격 증명을 위한 Token을 발급받기 위해 필요한 API를 설명합니다.

요청

권한 부여 후에, 또는 Refresh Token을 사용하여 Access Token이나 ID Token을 발급받기 위해 보내는 요청은 다음과 같습니다.

POST /tenants/{Tenant Id or Alias}/oauth2/token

• 요청 Path

  파라미터명	타입	필수 여부	제약 사항	설명
  Tenant Id or Alias	String	필수	-	Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias

• 요청 헤더

  헤더명	타입	필수 여부	제약 사항	설명
  Authorization	String	선택	Access Type이 public일 경우 사용, Basic Base64({Client Id}:{Client Secret})	Client 식별자
  Content-Type	String	필수	application/x-www-form-urlencoded	리소스의 미디어 타입

• 요청 파라미터

  파라미터명	타입	필수 여부	제약 사항	설명
  grant_type	String	필수	authorization_code 또는 refresh_token	Token 반환 방식
  code	String	선택	grant_type이 authorization_code 일 경우 사용	IDP가 전달한 Authorization code
  redirect_uri	String	선택	grant_type이 authorization_code 일 경우 사용	권한 부여 요청 시 포함한 redirect_uri
  scope	String	선택	grant_type이 refresh_token 일 경우 사용	수정할 scope
  code_verifier	String	선택	Access Type이 public일 경우 사용 , grant_type이 authorization_code 일 경우 사용되며, 기존에 부여한 scope의 범위보다 같거나 작아야 함	권한 부여 요청 시 포함한 code_challenge, code_challenge_method에 대응되는 값
  client_id	String	선택	Access Type이 public일 경우 사용	Application 등록 시 발급받은 Client ID

예시는 다음과 같습니다.

• 권한 부여 후 Authorization code를 포함하여 Access Token 발급을 요청할 경우

  POST /tenants/{Tenant Id or Alias}/oauth2/token HTTP/1.1
  Host: sso.ncloud.com
  Authorization: Basic Base64(${Client Id}:${Client Secret})
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code&code=${Authorization code}&redirect_uri=${Redirect URI}
  

• 권한 부여 후 Access Token 발급 요청에 code_verifier가 포함된 경우

  POST /tenants/{Tenant Id or Alias}/oauth2/token HTTP/1.1
  Host: sso.ncloud.com
  Authorization: Basic Base64(${Client Id}:${Client Secret})
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code&code=${Authorization code}&redirect_uri=${Redirect URI}&code_verifier=${Code Verifier}&client_id=${Client Id}
  

• Refresh Token으로 Access Token 발급을 요청할 경우

  POST /tenants/{Tenant Id or Alias}/oauth2/token HTTP/1.1
  Host: sso.ncloud.com
  Authorization: Basic Base64(${Client Id}:${Client Secret})
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=refresh_token&refresh_token=${Refresh Token}&scope=${Scope}  
  

응답

요청에 대한 응답은 다음과 같습니다.

{
  "access_token": "String",
  "token_type": "Bearer",
  "expires_in": "Number",
  "refresh_token": "String"
}

Token 취소

Access Token 또는 Refresh Token을 취소할 때 필요한 API를 설명합니다.

요청

Access Token 또는 Refresh Token을 취소하기 위해 보내는 요청은 다음과 같습니다.

POST /tenants/{Tenant Id or Alias}/oauth2/revoke

• 요청 Path

  파라미터명	타입	필수 여부	제약 사항	설명
  Tenant Id or Alias	String	필수	-	Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias

• 요청 헤더

  헤더명	타입	필수 여부	제약 사항	설명
  Authorization	String	필수	Basic Base64({Client Id}:{Client Secret})	Client 식별자
  Content-Type	String	필수	application/x-www-form-urlencoded	리소스의 미디어 타입

• 요청 파라미터

  파라미터명	타입	필수 여부	제약 사항	설명
  token	String	필수	-	취소하려는 Token
  token_type_hint	String	필수	access_token 또는 refresh_token	취소하려는 Token의 타입

응답

요청에 대한 응답은 다음과 같습니다.

{
  "status": "ok"
}

인증된 사용자의 클레임 반환

인증된 사용자에 대한 클레임을 반환하기 위해 필요한 API를 설명합니다.

요청

사용자 클레임을 반환하기 위해 보내는 요청은 다음과 같습니다.

POST /tenants/{Tenant Id or Alias}/oauth2/userinfo

• 요청 Path

  파라미터명	타입	필수 여부	제약 사항	설명
  Tenant Id or Alias	String	필수	-	Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias

• 요청 헤더

  헤더명	타입	필수 여부	제약 사항	설명
  Authorization	String	필수	Bearer {AccessToken}	Client 식별자

응답

요청에 대한 응답은 다음과 같습니다.

{
  "sub" : "String",
  "id_no" : "String",
  "user_type" : "String",
  "user_id": "String",
  "user_name" : "String",
  "mbr_no" : "Number"
  "groups" : "List"
}

ID Token 서명 키 반환

ID Token의 서명에 사용되는 공개 키를 반환할 때 필요한 API를 설명합니다.

요청

ID Token 서명에 사용되는 공개 키를 반환하기 위해 보내는 요청은 다음과 같습니다.

GET /tenants/{Tenant Id or Alias}/oauth2/jwks

• 요청 Path

  파라미터명	타입	필수 여부	제약 사항	설명
  Tenant Id or Alias	String	필수	-	Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias

응답

요청에 대한 응답은 다음과 같습니다.

{
  "keys" : [ {
    "kty" : "String",
    "e" : "String",
    "kid" : "String",
    "n" : "String"
  } ]
}

Endpoint

API의 Endpoint는 다음과 같습니다.