Foundry용 OAuth2 클라이언트 작성

이 문서는 Foundry에 연결하기 위해 OAuth2 클라이언트를 작성하려는 Foundry 사용자 또는 관리자를 위한 것입니다. 이 페이지는 OAuth 2.0 Authorization Framework ↗에 대한 설명과 Foundry의 OAuth2 구현에 대한 세부 정보를 제공합니다. 또한, Foundry 제3자 애플리케이션 및 API 계약은 Foundry 플랫폼에서 제3자 애플리케이션의 사용을 규정하며, 제3자 애플리케이션의 작성자 및 관리자가 이해해야 합니다.

OAuth2 개요

OAuth2 인증 프레임워크는 제3자 애플리케이션이 서비스에 대한 제어된 접근을 얻을 수 있도록 합니다. OAuth2는 전통적인 클라이언트-서버 인증 모델을 개선하여, 사용자의 자격 증명이나 정적 베어러 토큰 대신에 특정하게 발행된 액세스 토큰과 갱신 토큰을 사용하여 클라이언트(예: 제3자 애플리케이션)가 접근을 요청할 수 있는 계층을 제공합니다. OAuth2는 접근 토큰을 얻는 방법인 그랜트를 사용하여 이 접근을 관리합니다.

OAuth2 통합 지원

다음 섹션에서는 제3자 애플리케이션에서 OAuth2를 지원하는 방법을 설명합니다. 문서 전반에서 클라이언트는 제3자 애플리케이션을, 인증 서버는 Foundry의 인증 서버를, 사용자는 제3자 애플리케이션의 최종 사용자를 의미합니다.

Foundry와 OAuth2를 사용하려면 제3자 애플리케이션 등록 지침을 따르고 다음 하위 섹션에서 하나의 인증 옵션을 선택해야 합니다.

인증 코드 그랜트

인증 코드 그랜트는 클라이언트가 기존 Foundry 사용자를 대신하여 행동할 수 있도록 합니다. 애플리케이션은 필요한 Foundry 권한 세트를 요청해야 하며, 그런 다음 Foundry 사용자가 자신의 계정에서 해당 권한에 대한 클라이언트 접근을 명시적으로 허가해야 합니다. Foundry는 클라이언트가 제한된 리소스 세트에만 접근할 수 있도록 하거나 사용자가 접근할 수 있는 모든 리소스에 접근할 수 있도록 허용합니다.

인증 코드 그랜트는 다음과 같이 작동합니다:

1. 클라이언트는 code_verifier와 code_challenge를 생성합니다. 이는 기밀 클라이언트 ↗, 예를 들어 클라이언트 비밀을 안전하게 저장할 수 있는 서버 기반 애플리케이션에 대해서는 권장되지만 필수는 아닙니다. 이는 클라이언트 비밀을 안전하게 저장할 수 없는 공개 클라이언트 ↗, 예를 들어 네이티브 앱에 대해서는 필수입니다.
   • code_verifier는 A-Z, a-z, 0-9, - (하이픈), . (마침표), _ (밑줄), ~ (틸드)를 포함하는 암호학적으로 무작위 스트링이며, 43에서 128자 사이입니다.
   • code_challenge는 code_verifier의 SHA256을 수행한 후 패딩 없이 Base64-URL-인코딩된 값으로 변환하여 파생됩니다.
2. 클라이언트 애플리케이션은 브라우저를 열고 사용자를 인증 엔드포인트 URL로 보내야 하며, 다음 파라미터를 쿼리 파라미터로 추가해야 합니다:
   • response_type: 이는 code로 설정해야 합니다.
   • client_id: 이는 Foundry에 제3자 애플리케이션이 등록될 때 생성된 ID로 설정해야 합니다.
   • redirect_uri: 이는 사용자가 요청을 승인한 후 인증 서버가 사용자를 리디렉션할 위치를 알려줍니다. 지정하지 않으면 Foundry의 제3자 애플리케이션 설정에서 첫 번째 리디렉션 URI 값으로 기본 설정됩니다.
   • scope: 이는 요청된 권한을 정의합니다. 공개 API의 범위는 API 문서에 있습니다. 갱신 토큰을 받으려면 offline_access 범위를 추가하세요. 여러 범위를 원하면 공백을 구분자로 사용하여 범위를 연결하세요.
   • state: 이는 애플리케이션이 생성한 임의의 스트링으로, 애플리케이션에 그대로 전달됩니다. 애플리케이션은 반환된 값이 원래 스트링과 일치하는지 확인하여 CSRF 공격을 방지해야 합니다.
   • code_challenge: 클라이언트가 code_challenge를 생성했으면 이 파라미터를 채워야 합니다. 인증 서버는 내부적으로 생성한 인증 코드와 code_challenge 파라미터를 연결합니다.
   • code_challenge_method: 이는 S256으로 설정해야 합니다.
3. 사용자가 URL을 방문하면 인증 서버는 사용자에게 다음과 유사한 프롬프트를 표시하며 사용자는 앱의 요청을 승인할 수 있습니다.

4. 요청이 성공하면 인증 서버는 사용자를 지정된 리디렉션 URI로 리디렉션하며, 다음 파라미터를 쿼리 파라미터로 추가합니다:
   • code: 이는 인증 서버가 생성한 인증 코드입니다.
   • state: 이는 클라이언트가 인증 요청에서 전달한 동일한 파라미터입니다. 클라이언트는 요청에서 보낸 원래 state 파라미터와 일치하는지 확인해야 합니다.
5. 클라이언트는 토큰 엔드포인트를 호출하여 인증 코드를 액세스 토큰으로 교환해야 합니다. 다음 파라미터는 요청 본문에서 application/x-www-form-urlencoded 형식으로 전송해야 합니다:
   • grant_type: 이는 authorization_code로 설정해야 합니다.
   • code: 인증 서버에서 받은 코드입니다.
   • redirect_uri: 사용자 에이전트가 리디렉션될 절대 URI입니다.
   • client_id: 이는 Foundry에 제3자 애플리케이션이 등록될 때 생성된 ID로 설정해야 합니다.
   • code_verifier: 클라이언트가 code_verifier를 생성했으면 이 요청에 포함해야 합니다. 인증 서버는 code_verifier가 이전 요청에서 보낸 code_challenge와 일치하는지 확인합니다.
6. 인증 서버는 요청된 리소스(예: REST API)에 접근할 수 있는 액세스 토큰을 클라이언트에게 응답합니다. 응답에는 다음 파라미터가 포함됩니다:
   • access_token: 클라이언트가 요청된 리소스에 접근할 수 있는 토큰입니다.
   • token_type: 발행된 토큰의 유형입니다.
   • expires_in: 액세스 토큰의 수명(초)입니다.
   • refresh_token: 요청된 범위에 offline_access가 포함된 경우에만 반환됩니다. 클라이언트가 사용자가 요청을 승인하지 않고 액세스 토큰을 갱신하려는 경우 사용해야 합니다. 자세한 내용은 액세스 토큰 갱신을 참조하세요.

클라이언트 자격 증명 그랜트

클라이언트 자격 증명 그랜트는 클라이언트가 일반 Foundry 사용자와 연관되지 않은 비대화형 서비스 사용자 스타일의 워크플로를 위해 설계되었습니다. 클라이언트는 일반 Foundry 사용자를 대신하여 행동하지 않습니다.

대신 이 그랜트 유형은 클라이언트와 연관된 Foundry 서비스 사용자를 자동으로 생성하며, 이후 Foundry 리소스에 접근할 수 있는 권한을 부여받을 수 있습니다. 이 그랜트로 얻은 토큰은 생성된 서비스 사용자를 대신하여 리소스에 접근하는 데 사용할 수 있습니다. 서비스 사용자 계정의 사용자 이름은 애플리케이션의 클라이언트 ID와 동일합니다.

클라이언트 자격 증명 그랜트는 다음과 같이 작동합니다:

1. 클라이언트는 토큰 엔드포인트를 호출합니다. 다음 파라미터는 요청 본문에서 application/x-www-form-urlencoded 형식으로 전송해야 합니다:
   • grant_type: 이는 client_credentials로 설정해야 합니다.
   • client_id: 이는 Foundry에 제3자 애플리케이션이 등록될 때 생성된 ID로 설정해야 합니다.
   • client_secret: 이는 Foundry에 제3자 애플리케이션이 등록될 때 생성된 클라이언트 비밀로 설정해야 합니다.
2. 인증 서버는 다음과 같이 응답합니다:
   • access_token: 클라이언트가 요청된 리소스에 접근할 수 있는 토큰입니다.
   • token_type: 발행된 토큰의 유형입니다.
   • expires_in: 액세스 토큰의 수명(초)입니다.
3. 클라이언트는 액세스 토큰을 사용하여 요청된 리소스에 접근할 수 있습니다.

액세스 토큰 갱신

액세스 토큰은 일정 시간이 지나면 만료되며 다시 얻어야 합니다. 사용자가 없는 상태에서 Foundry API에 접근해야 하는 모든 클라이언트는 토큰을 갱신해야 합니다.

이는 다음 단계를 따라 수행할 수 있습니다:

1. 클라이언트는 인증 코드 그랜트에 설명된 단계를 따르고 요청된 scope 파라미터의 일부로 offline_access를 지정해야 합니다.
2. 클라이언트는 인증 코드 그랜트의 마지막 단계에서 반환된 refresh_token을 저장해야 합니다.
3. 액세스 토큰이 만료되면 클라이언트는 다음 파라미터를 사용하여 토큰 엔드포인트 엔드포인트를 호출하여 토큰을 갱신할 수 있습니다:
   • grant_type: 이는 refresh_token으로 설정해야 합니다.
   • refresh_token: 주어진 사용자에 대해 이전에 얻은 갱신 토큰입니다.
   • client_id: 이는 Foundry에 제3자 애플리케이션이 등록될 때 생성된 ID로 설정해야 합니다.
   • client_secret: 이는 Foundry에 제3자 애플리케이션이 등록될 때 생성된 클라이언트 비밀로 설정해야 합니다.
4. 인증 서버는 다음과 같이 응답합니다:
   • access_token: 클라이언트가 요청된 리소스에 접근할 수 있는 토큰입니다.
   • token_type: 발행된 토큰의 유형입니다.
   • expires_in: 액세스 토큰의 수명(초)입니다.
   • refresh_token: 액세스 토큰을 갱신하는 데 사용할 수 있는 갱신 토큰입니다. Foundry는 이전에 발행된 갱신 토큰이 사용될 때마다 갱신 토큰을 회전합니다. access_token과 refresh_token을 모두 저장하세요.

갱신 토큰 회전

갱신 토큰은 새로운 액세스 토큰을 얻는 데 사용할 수 있습니다. Foundry는 갱신 토큰이 사용될 때마다 갱신 토큰을 회전하여 갱신 토큰과 관련된 위험을 줄입니다. 재사용 감지 보호 메커니즘은 갱신 토큰이 처음 사용된 후 1분 후에 재사용되면 이 그랜트에서 생성된 모든 액세스 토큰이 무효화되고 새로운 인증 흐름이 필요하도록 보장합니다. 네트워크 오류와 같은 일시적인 오류를 고려하여 1분 간의 재사용 간격이 허용됩니다. 또한, 30일 이상 비활성화된 갱신 토큰은 자동으로 무효화됩니다. 이러한 안전장치는 잠재적으로 손상된 토큰으로 인한 위험을 줄이며, 장기간 유효한 갱신 토큰이 없도록 보장합니다.

OAuth2 API 출처

다음 엔드포인트는 OAuth2 토큰을 얻는 데 사용할 수 있습니다.

인증 엔드포인트

GET /multipass/api/oauth2/authorize

클라이언트가 인증 코드를 얻기 위해 사용하는 인증 엔드포인트입니다.

쿼리 파라미터

리디렉션 쿼리 파라미터

요청이 성공하면 사용자의 브라우저는 제3자 애플리케이션 설정에 지정된 리디렉션 URI 또는 요청에 전달된 리디렉션 URI로 리디렉션됩니다. 리디렉션 요청 URI에는 다음 쿼리 파라미터가 포함됩니다:

토큰 엔드포인트

POST /multipass/api/oauth2/token

토큰 엔드포인트는 클라이언트가 인증 그랜트 또는 갱신 토큰을 제시하여 액세스 토큰을 얻는 데 사용됩니다.

헤더 파라미터

요청 본문 파라미터

응답 본문

응답 JSON에는 다음 필드가 포함됩니다.

엔드포인트 오류

오류 응답 본문

요청이 실패하면, 접근 요청이 거부된 경우에만 사용자의 브라우저가 리디렉션됩니다. 다른 모든 경우에는 아래 필드를 포함한 HTML 오류 페이지가 반환됩니다.

오류 코드