Application 연동 API
    • PDF

    Application 연동 API

    • PDF

    기사 요약

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

    참고
    • Ncloud Single Sign-On 연동 API를 사용하기 전에 OAuth 2.0과 관련된 주요 개념을 Ncloud Single Sign-On 개념에서 학습하는 것을 권장합니다.
    • 여기에서는 Ncloud Single Sign-On 연동 시 사용하는 API만 설명합니다. 네이버 클라우드 플랫폼의 Ncloud Single Sign-On이 제공하는 전체 API에 대한 설명은 Ncloud Single Sign-On API 가이드를 참고해 주십시오.

    권한 부여

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

    요청

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

    GET /tenants/{Tenant Id or Alias}/oauth2/authorize
    
    • 요청 Path
      파라미터명타입필수 여부제약 사항설명
      Tenant Id or AliasString필수-Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias
    • 요청 파라미터
      파라미터명타입필수 여부제약 사항설명
      response_typeString필수code 또는 tokenAuthorization Code 또는 Implicit 플로우 진행 시 필요한 값
      client_idString필수-Application 등록 시 발급받은 Client ID
      redirect_uriString필수Application 등록 시 입력한 Redirect URI와 반드시 일치권한 부여 완료 후 이동하게 되는 페이지의 URL
      scopeString필수-접근 가능 범위. 추가 범위를 요청하기 위해서는 하나 이상의 범위 값을 공백으로 구분하여 포함.
      stateString선택-CSRF 방어를 위한 임의의 값. state 권한 부여 완료 후 state를 포함해 redirect_uri에 입력한 페이지로 이동
      code_challengeString선택Access Type이 public일 경우 사용PKCE 적용 시 필요한 Code Challenge의 값
      code_challenge_methodString선택Access Type이 public일 경우 사용, plain 또는 S256PKCE 적용 시 필요한 Code Challenge Method의 값

    예시는 다음과 같습니다.

    • response_typecode인 경우

      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_challengecode_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_typetoken인 경우

      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_typecode인 경우

      HTTP/1.1 302 Found
      Location: {Redirect URI}
      ?code=${Authorization code}
      &state=${State}
      
      파라미터명타입필수 여부제약 사항설명
      redirect_uriString필수요청 시 포함한 redirect_uri권한 부여 완료 후 이동하게 되는 페이지의 URL
      codeString필수유출 위험을 방지하기 위해 1분 후 만료IDP에서 생성한 Authorization code
      stateString선택-Client가 요청한 값
    • response_typetoken인 경우

      HTTP/1.1 302 Found
      Location: {Redirect URI}
      ?access_token={Access Token}
      &token_type=Bearer
      &expires_in={Access Token Expire Date}
      &state={State}
      
      파라미터명타입필수 여부제약 사항설명
      redirect_uriString필수요청 시 포함한 redirect_uri권한 부여 완료 후 이동하게 되는 페이지의 URL
      access_tokenString필수-권한이 부여된 Access Token
      expires_inNumber필수-Access Token의 유효 기간
      stateString선택-Client가 요청한 값

    Token 발급

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

    요청

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

    POST /tenants/{Tenant Id or Alias}/oauth2/token
    
    • 요청 Path
      파라미터명타입필수 여부제약 사항설명
      Tenant Id or AliasString필수-Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias
    • 요청 헤더
      헤더명타입필수 여부제약 사항설명
      AuthorizationString선택Access Type이 public일 경우 사용, Basic Base64({Client Id}:{Client Secret})Client 식별자
      Content-TypeString필수application/x-www-form-urlencoded리소스의 미디어 타입
    • 요청 파라미터
      파라미터명타입필수 여부제약 사항설명
      grant_typeString필수authorization_code 또는 refresh_tokenToken 반환 방식
      codeString선택grant_typeauthorization_code 일 경우 사용IDP가 전달한 Authorization code
      redirect_uriString선택grant_typeauthorization_code 일 경우 사용권한 부여 요청 시 포함한 redirect_uri
      scopeString선택grant_typerefresh_token 일 경우 사용수정할 scope
      code_verifierString선택Access Type이 public일 경우 사용 , grant_typeauthorization_code 일 경우 사용되며, 기존에 부여한 scope의 범위보다 같거나 작아야 함권한 부여 요청 시 포함한 code_challenge, code_challenge_method에 대응되는 값
      client_idString선택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"
    }
    
    파라미터명타입필수 여부제약 사항설명
    access_tokenString필수-권한이 부여된 Access Token
    token_typeString필수BearerToken의 형식
    expires_inNumber필수-Access Token의 유효 기간
    refresh_tokenString필수-Access Token 발급 시 사용되는 Refresh Token의 값

    Token 취소

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

    요청

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

    POST /tenants/{Tenant Id or Alias}/oauth2/revoke
    
    • 요청 Path
      파라미터명타입필수 여부제약 사항설명
      Tenant Id or AliasString필수-Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias
    • 요청 헤더
      헤더명타입필수 여부제약 사항설명
      AuthorizationString필수Basic Base64({Client Id}:{Client Secret})Client 식별자
      Content-TypeString필수application/x-www-form-urlencoded리소스의 미디어 타입
    • 요청 파라미터
      파라미터명타입필수 여부제약 사항설명
      tokenString필수-취소하려는 Token
      token_type_hintString필수access_token 또는 refresh_token취소하려는 Token의 타입

    응답

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

    {
      "status": "ok"
    }
    

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

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

    요청

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

    POST /tenants/{Tenant Id or Alias}/oauth2/userinfo
    
    • 요청 Path
      파라미터명타입필수 여부제약 사항설명
      Tenant Id or AliasString필수-Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias
    • 요청 헤더
      헤더명타입필수 여부제약 사항설명
      AuthorizationString필수Bearer {AccessToken}Client 식별자

    응답

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

    {
      "sub" : "String",
      "id_no" : "String",
      "user_type" : "String",
      "user_id": "String",
      "user_name" : "String",
      "mbr_no" : "Number"
      "groups" : "List"
    }
    
    파라미터명타입필수 여부제약 사항설명
    subString필수-Subject(end-user) 식별자
    id_noString필수-네이버 클라우드 플랫폼에서 사용되는 사용자 식별자
    user_typeString필수Customer 또는 Sub사용자 유형
    user_idString필수-로그인 아이디
    user_nameString필수-사용자 이름
    mbr_noNumber필수-사용자의 회원 번호
    groupsList선택-user_typeSub일 때 subAccount가 속한 그룹명 목록

    ID Token 서명 키 반환

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

    요청

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

    GET /tenants/{Tenant Id or Alias}/oauth2/jwks
    
    • 요청 Path
      파라미터명타입필수 여부제약 사항설명
      Tenant Id or AliasString필수-Tenant 생성 시 발급받은 Tenant ID 또는 Tenant Alias

    응답

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

    {
      "keys" : [ {
        "kty" : "String",
        "e" : "String",
        "kid" : "String",
        "n" : "String"
      } ]
    }
    
    파라미터명타입필수 여부제약 사항설명
    ktyString필수-IETF Datatracker의 Key Type 참고
    eString필수-IETF Datatracker의 RSA Exponent 참고
    kidString필수-IETF Datatracker의 Key ID 참고
    nString필수-IETF Datatracker의 RSA Modulus 참고

    Endpoint

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

    EndpointURI Path설명
    Authorization Endpoint/tenants/{Tenant Id or Alias}/oauth2/authorizeClient가 Resource Owner와 상호 작용하고 보호된 리소스에 접근할 수 있는 권한 부여 요청
    Token Endpoint/tenants/{Tenant Id or Alias}/oauth2/token접근 권한 또는 Refresh Token을 통해 Access Token, ID Token 발급
    Token Revocation Endpoint/tenants/{Tenant Id or Alias}/oauth2/revokeAccess Token 또는 Refresh Token 취소
    User Info Endpoint/tenants/{Tenant Id or Alias}/oauth2/userinfo인증된 사용자에 대한 클레임 반환

    이 문서가 도움이 되었습니까?

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.