oauth

Okta OAuth

Okta OAuth는 Okta API와 상호작용할 때 스코프(scope) 기반의 OAuth 2.0 액세스 토큰을 사용하는 방법을 설명하는 기능이에요. 대부분의 Okta API 엔드포인트는 요청에 API 토큰(SSWS 토큰)을 포함해야 했는데, OAuth for Okta를 사용하면 스코프가 지정된 OAuth 2.0 액세스 토큰을 사용해서 Okta API와 소통할 수 있어요. 각 액세스 토큰은 보유자(bearer)가 특정 Okta 엔드포인트에서 특정 작업을 수행할 수 있게 하며, 토큰 안의 스코프가 그 권한을 제어해요.

출처: 문서

본문

Okta OAuth는 Okta API를 스코프 기반 OAuth 2.0 액세스 토큰으로 다루는 기능이에요. 스코프가 지정된 액세스 토큰은 다음과 같은 장점이 있어요.

  • 더 세밀한 접근 권한(granularity)
  • 더 짧은 토큰 수명
  • API를 통해 생성하고 조회 가능

중요 액세스 토큰은 Okta 조직 인가 서버(org authorization server)의 /authorize 엔드포인트에서 요청하세요. Okta API 스코프를 담은 액세스 토큰을 발급할 수 있는 것은 오직 조직 인가 서버뿐이에요.

참고 OAuth for Okta는 OAuth 2.0 Scopes 페이지에 나열된 API에서만 동작해요.

Okta에 OAuth 2.0 앱 만들기

Okta API와 함께 사용할 클라이언트 앱을 생성해요.

  1. 관리자 계정으로 Okta 조직에 로그인해요.
  2. Admin Console에서 Applications and Resources > Applications로 이동해요.
  3. Create App Integration을 클릭해요.
  4. Sign-in method로 OIDC - OpenID Connect를 선택해요.
  5. Application type은 Web Application을 선택해요. 웹 앱을 만들면 OAuth 2.0 bearer 토큰으로 Okta API에 스코프 기반 접근을 테스트하기 쉬워요. Next를 클릭해요.
  6. 앱 통합 이름을 입력해요.
  7. Grant type으로 Authorization Code가 필요해요. 기본 선택되어 있고 체크박스를 해제할 수 없어요.
  8. Sign-in redirect URIs에 사용자가 인증한 후 Okta가 브라우저(및 토큰)를 반환할 콜백 위치를 지정해요.
  9. Assignments 섹션에서 Limit access to selected groups를 선택하고 그룹을 추가하거나 Skip group assignment for now를 선택해요.
  10. Save를 클릭해요. Client Credentials 섹션에 표시된 Client ID와 Client secret을 기록해두세요.
  11. Assignments 탭에서 올바른 사용자가 앱에 할당되었는지 확인해요.
  12. 선택 사항으로 Application rate limits 탭을 클릭해 앱의 요청 속도 제한 용량 비율을 조정해요. 기본값은 50%예요.

참고로 public client 앱에서는 적절한 앱 유형을 선택하는 것이 중요해요. 잘못된 유형을 선택하면 Okta API 엔드포인트가 앱의 client secret을 검증하려 하게 되는데, public client는 이를 갖도록 설계되지 않아서 로그인/로그아웃 플로우가 깨질 수 있어요.

허용된 스코프 정의하기

조직 인가 서버의 /authorize 엔드포인트로 요청을 보내면, 요청의 모든 스코프를 앱의 grants 컬렉션과 대조해 검증해요. 스코프가 앱의 grants 컬렉션에 있으면 부여돼요.

참고 앱에 스코프를 부여할 수 있는 권한은 Super Admin 역할뿐이에요.

  1. 관리자 계정으로 Okta 조직에 로그인해요.
  2. Admin Console에서 Applications and Resources > Applications로 이동해요.
  3. grants를 추가할 OpenID Connect(OIDC) 또는 OAuth 2.0 앱을 선택해요.
  4. Okta API Scopes 탭을 선택한 뒤 추가할 각 스코프에 대해 Grant를 클릭해요. 이 예시에서는 okta.users.read에 대한 접근 권한을 부여해요.

또는 Apps API로 grants를 추가할 수 있어요. okta.users.read 스코프의 grant를 생성하는 예시 요청이에요.

curl --location --request POST 'https://{yourOktaDomain}/api/v1/apps/{appInstanceId}/grants' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: SSWS ***' \
--data-raw '{
    "scopeId": "okta.users.read",
    "issuer": "https://{yourOktaDomain}"
}'

액세스 토큰 받고 요청 보내기

다음이 준비되면 액세스 토큰을 받아 엔드포인트에 요청할 수 있어요.

  • Okta OpenID Connect 또는 OAuth 2.0 서비스 앱
  • 해당 앱과 연결된 하나 이상의 grants
  • 적절한 권한을 가진 앱 연결 사용자
  • Okta에서 적절한 관리자 권한을 가진 사용자

액세스 토큰은 Okta 조직 인가 서버의 /authorize 엔드포인트에 요청해서 받아요. Okta API 스코프를 담은 액세스 토큰을 발급할 수 있는 것은 오직 조직 인가 서버뿐이에요. 요청 URL은 대략 다음과 같은 형태예요.

https://{yourOktaDomain}/oauth2/v1/authorize?client_id=0oan47pj9BsB30h7&response_type=token&response_mode=fragment&scope=okta.users.read&redirect_uri={yourConfiguredRedirectUri}&nonce=UBGW&state=1234

Okta는 항상 Authorization Code with PKCE grant 플로우를 사용하길 권장해요. 아래는 Postman에서 토큰을 구성하는 방법이에요.

  1. Postman에서 /api/v1/users 엔드포인트에 대한 GET 요청 같은 것을 선택해요.
  2. Header 탭에서 기존 SSWS Authorization API Key를 제거해요.
  3. Authorization 탭을 클릭하고 Auth Type 드롭다운에서 OAuth 2.0을 선택해요.
  4. 오른쪽 창의 Configure New Token 섹션으로 이동해요.
  5. 토큰 이름을 입력하고 grant type으로 **Authorization Code (With PKCE)**를 선택해요.
  6. 토큰 요청의 나머지 필드를 정의해요.
    • Callback URL: Okta가 인증 후 토큰을 반환할 콜백 위치. 앱에 구성한 redirect URI 중 하나와 일치해야 해요.
    • Auth URL: 조직 인가 서버의 인가 엔드포인트, 예: https://{yourOktaDomain}/oauth2/v1/authorize.
    • Access Token URL: 조직 인가 서버의 토큰 엔드포인트, 예: https://{yourOktaDomain}/oauth2/v1/token.
    • Client ID: 만든 Okta OAuth 2.0 앱의 client_id.
    • Client secret: 만든 Okta OAuth 2.0 앱의 client_secret.
    • Code Challenge Method: 기본값인 SHA-256을 유지해요.
    • Code Verifier: 비워두면 Postman이 자동 생성해요.
    • Scope: 이 예시에서는 okta.users.read를 사용해요. 접근하려는 엔드포인트에서 작업을 수행할 수 있게 해주는 스코프를 포함하세요. 요청한 스코프는 앱의 grants 컬렉션에 있어야 하고 사용자에게 해당 작업 권한이 있어야 해요.
    • State: 기본값 또는 임의의 영숫자 값을 사용해요. 인가 서버는 브라우저를 클라이언트로 리다이렉트할 때 이 문자열을 그대로 반영하며, 클라이언트는 이 값을 검증해 CSRF(사이트 간 요청 위조) 공격을 막을 수 있어요.
    • Client Authentication: Send client credentials in body로 설정해요.
  7. Get New Access Token을 클릭해요. Okta 조직에 로그인하라는 프롬프트가 표시돼요.
  8. OIDC 앱에 할당한 사용자로 로그인해요. 인증 후 Manage Access Tokens 창에 요청한 스코프를 포함한 액세스 토큰이 표시돼요.
  9. Use Token을 클릭해 /users 엔드포인트 요청에 이 액세스 토큰을 사용해요.
  10. Send를 클릭해요. okta.users.read를 요청했으므로 응답에 앱과 연결된 모든 사용자 배열이 포함돼요.

참고 이 토큰의 수명은 1시간으로 고정돼요.

스코프와 지원 엔드포인트

OAuth 2.0을 지원하는 엔드포인트의 모든 작업에는 특정 스코프가 필요해요. Okta 스코프 형식은 okta.<resource name>.<operation>이에요. 예를 들어 users, clients, apps 같은 리소스에 read 또는 manage 작업을 가질 수 있어요. read 스코프는 리소스 정보를 읽는 데 쓰이고, manage 스코프는 리소스를 생성·관리·삭제하는 데 쓰여요.

okta.<resource>.read 스코프로 GET API 작업을 수행하고, okta.<resource>.manage 스코프로 GET 작업과 POST, PUT, DELETE API 작업을 수행해요. self 스코프(okta.<resource>.<operation>.self)는 토큰을 인가한 사용자에게만 접근을 허용하며, 엔드 사용자 API 작업에 사용돼요.

브라우저에서 cross-origin 시나리오로 bearer 토큰을 사용해 모든 엔드포인트에 접근할 수 있어요. Trusted Origin을 구성할 필요가 없어요. OAuth for Okta API가 쿠키에 의존하지 않고 bearer 토큰을 사용하기 때문이에요.

스코프 명명 규칙

스코프는 계층 구조로 존재해서 manage 스코프가 read 스코프가 하는 모든 것을 더 많이 할 수 있어요. 또한 self 스코프는 토큰을 인가한 사용자에게만 접근을 허용해요. 예를 들어 /users 엔드포인트에 okta.users.read 스코프로 GET 요청을 보내면 관리자가 접근할 수 있는 모든 사용자를 반환하지만, 같은 요청을 okta.users.read.self 스코프로 보내면 현재 사용자 계정만 반환해요.

자동 다운스코핑(Silent downscoping)

Okta 조직 인가 서버는 요청한 모든 스코프를 반환해요. 클라이언트 앱이 해당 스코프를 사용하도록 허용(부여)된 한 요청한 모든 스코프가 반환되며, 요청한 스코프 전부에 대한 권한이 있는지는 중요하지 않아요. 요청한 스코프가 앱의 grants 컬렉션에 존재하면 그 스코프들이 액세스 토큰에 담겨 반환돼요. 다만 권한이 없는 작업을 수행하려고 요청하면 토큰이 동작하지 않고 오류가 발생해요.

예를 들어 Read Only Admin이 okta.authorizationServers.manage 스코프를 담은 액세스 토큰을 요청했고 그 스코프가 클라이언트의 grants 컬렉션에 존재한다면, 반환된 액세스 토큰에는 그 스코프가 포함돼요. 하지만 /api/v1/authorizationServers에서 인가 서버를 수정하려고 하면 권한이 없으므로 토큰이 동작하지 않아요.

더 알아보기 (Learn more)