Application integration API

Available in Classic and VPC

This section describes how to integrate registered applications with Single Sign-On. Integration is carried out through the integration API provided by Single Sign-On. The features provided by the Single Sign-On integration API are as follows:

• Grant permissions
• Issue tokens
• Cancel tokens
• Return authenticated user claims
• Return ID token signature key

Grant permissions

This section describes the APIs required to interact with the resource owner and obtain permissions to access protected resources.

Requests

The request sent by the client to the IDP to access protected resources is as follows:

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

• Request path

  Parameter name	Type	Requirement status	Restrictions	Description
  Tenant Id or Alias	String	Required	-	Tenant ID or tenant alias issued when creating a tenant

• Request parameters

  Parameter name	Type	Requirement status	Restrictions	Description
  response_type	String	Required	code or token	Values required when proceeding with the authorization code or implicit flow
  client_id	String	Required	-	Client ID issued when registering the application
  redirect_uri	String	Required	Must match the redirect URI entered when registering the application	The URL of the page you will be directed to after granting permissions
  scope	String	Required	-	Accessible scope. To request additional scopes, include one or more scope values separated by a space.
  state	String	Optional	-	A random value for CSRF defense. After granting state permissions, go to the page entered in redirect_uri, including the state value
  code_challenge	String	Optional	-	The value of the code challenge required when applying PKCE
  code_challenge_method	String	Optional	plain or S256	The value of the code challenge method required when applying PKCE

See below for an example.

• If response_type is 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
  

• If you requested permissions by adding code_challenge and 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
  

• If response_type is 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

The response to the request is as follows:

• If response_type is code

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

  Parameter name	Type	Requirement status	Restrictions	Description
  redirect_uri	String	Required	redirect_uri included in the request	The URL of the page you will be directed to after granting permissions
  code	String	Required	Expires after 1 minute to prevent the risk of leakage	Authorization code generated by the IDP
  state	String	Optional	-	Value requested by the client

• If response_type is token

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

  Parameter name	Type	Requirement status	Restrictions	Description
  redirect_uri	String	Required	redirect_uri included in the request	The URL of the page you will be directed to after granting permissions
  access_token	String	Required	-	Permission granted access token
  expires_in	Number	Required	-	Access token's validity period
  state	String	Optional	-	Value requested by the client

Issue tokens

Describes the API necessary to obtain a token for credentials after access permissions have been granted.

Requests

After granting permissions or using a refresh token, the request sent to obtain an access token or ID token is as follows:

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

• Request path

  Parameter name	Type	Requirement status	Restrictions	Description
  Tenant Id or Alias	String	Required	-	Tenant ID or tenant alias issued when creating a tenant

• Request headers

  Header name	Type	Requirement status	Restrictions	Description
  Authorization	String	Required	Basic Base64	Client identifier
  Content-Type	String	Required	application/x-www-form-urlencoded	Media type of the resource

• Request parameters

  Parameter name	Type	Requirement status	Restrictions	Description
  grant_type	String	Required	authorization_code or refresh_token	Token return method
  code	String	Optional	Use this if grant_type is authorization_code	Authorization code delivered by IDP
  redirect_uri	String	Optional	Use this if grant_type is authorization_code	redirect_uri included in the permission grant request
  scope	String	Optional	Use this if grant_type is refresh_token	scope to edit
  code_verifier	String	Optional	Used if grant_type is authorization_code, and it must be equal to or smaller than the scope previously granted	Values corresponding to code_challenge, code_challenge_method included in the permission request

See below for an example.

• When requesting the issuance of an access token including the authorization code after permission has been granted

  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}
  

• If code_verifier is included in the access token issuance request after granting permissions

  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}
  

• When requesting an access token with a refresh 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}  
  

Response

The response to the request is as follows:

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

Cancel tokens

Describes the API required to revoke an access token or refresh token.

Requests

The request to revoke an access token or refresh token is as follows:

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

• Request path

  Parameter name	Type	Requirement status	Restrictions	Description
  Tenant Id or Alias	String	Required	-	Tenant ID or tenant alias issued when creating a tenant

• Request headers

  Header name	Type	Requirement status	Restrictions	Description
  Authorization	String	Required	Basic Base64	Client identifier
  Content-Type	String	Required	application/x-www-form-urlencoded	Media type of the resource

• Request parameters

  Parameter name	Type	Requirement status	Restrictions	Description
  token	String	Required	-	The token to be revoked
  token_type_hint	String	Required	access_token or refresh_token	The type of the token to be revoked

Response

The response to the request is as follows:

{
  "status": "ok"
}

Return authenticated user claims

Describes the API required to return claims for authenticated users.

Requests

The request to return a user claim is as follows:

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

• Request path

  Parameter name	Type	Requirement status	Restrictions	Description
  Tenant Id or Alias	String	Required	-	Tenant ID or tenant alias issued when creating a tenant

• Request headers

  Header name	Type	Requirement status	Restrictions	Description
  Authorization	String	Required	Bearer	Client identifier

Response

The response to the request is as follows:

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

Return ID token signature key

Describes the API required to return the public key used to sign the ID token.

Requests

The request to send to return the public key used to sign the ID token is as follows:

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

• Request path

  Parameter name	Type	Requirement status	Restrictions	Description
  Tenant Id or Alias	String	Required	-	Tenant ID or tenant alias issued when creating a tenant

Response

The response to the request is as follows:

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

Endpoint

The API endpoint is as follows: