SAML 어설션 속성 구성하기

SAML 속성은 인증된 사용자에 대한 특정 정보를 담고 있는 SAML 어설션의 핵심 요소입니다. 이러한 속성에는 사용자 식별자, 역할 (역할), 권한 (권한), 그리고 서비스 제공자 (SP)가 인가 (Authorization) 및 개인화 목적으로 필요로 할 수 있는 기타 관련 사용자 데이터가 포함될 수 있습니다.

SAML 속성 이해하기

SAML 인증 (Authentication)에서:

속성은 사용자 정보를 담고 있는 이름-값 쌍입니다.
이들은 아이덴티티 제공자 (Logto)에서 서비스 제공자에게 전달되는 SAML 어설션에 포함됩니다.
서비스 제공자가 사용자 접근 및 개인화에 대해 정보에 기반한 결정을 내릴 수 있도록 돕습니다.

Logto에서의 속성 매핑

속성 매핑을 통해 Logto의 사용자 정보를 SAML 어설션의 특정 속성에 어떻게 매핑할지 정의할 수 있습니다. 이 매핑을 통해 서비스 제공자가 예상하는 형식과 속성 이름으로 사용자 정보를 받을 수 있습니다.

속성 매핑을 구성할 때:

SAML 어설션에 포함할 Logto의 사용자 속성을 지정합니다.
서비스 제공자가 기대하는 사용자 지정 속성 이름을 정의합니다.
매핑된 속성은 인증 (Authentication) 과정에서 자동으로 SAML 어설션에 포함됩니다.

일반적으로 사용되는 속성

일반적으로 사용되는 SAML 속성에는 다음이 포함됩니다:

Sub (사용자 ID)
Email
조직 (Organizations)
Name
Preferred username

Logto에서 제공하는 모든 사용자 데이터 보기

속성 매핑을 올바르게 구성하면, 서비스 제공자가 사용자에게 적절한 접근 및 개인화를 제공하는 데 필요한 모든 사용자 정보를 받을 수 있습니다.

속성 매핑 설정을 사용하여 Logto에서 제공하는 모든 사용자 정보를 서비스 제공자가 기대하는 속성에 매핑할 수 있습니다.

정적 속성

일부 서비스 제공자는 모든 사용자에게 동일한 값을 갖는 속성을 기대합니다. 예를 들어, 서비스 제공자 측에서 귀하의 계정 또는 사이트를 식별하는 ID 등이 있습니다. 정적 속성은 Logto가 애플리케이션의 모든 SAML 어설션에 매핑된 사용자 속성과 함께 추가하는 고정된 이름-값 쌍입니다.

예를 들어, NetSuite SuiteCommerce 통합에서는 account 및 site 속성을 기대할 수 있습니다:

속성 이름	값
`account`	귀하의 NetSuite 계정 ID
`site`	귀하의 웹사이트 ID

Console에서 정적 속성 구성하기

Console > Applications로 이동하여 SAML 애플리케이션을 엽니다.
Attribute mappings 탭을 열고 Base attribute mappings 아래의 Static attributes 카드를 찾습니다.
Key에 속성 이름을, Value에 값을 입력합니다. Add another를 클릭하여 속성을 추가할 수 있습니다. 마지막 속성을 제거하려면 해당 key와 value를 비우세요.
Save changes를 클릭합니다.

Management API로 정적 속성 구성하기

Management API를 사용하여 SAML 애플리케이션을 생성하거나 업데이트할 때 staticAttributes를 설정하세요:

curl \
  --request PATCH \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{"staticAttributes": {"account": "<your-account-id>", "site": "<your-site-id>"}}' \
  'https://[tenant-id].logto.app/api/saml-applications/<application-id>'

staticAttributes가 포함된 업데이트는 전체 객체를 대체하므로, 유지하고 싶은 모든 정적 속성을 포함해야 합니다. 변경하지 않으려면 해당 필드를 생략하고, 모두 제거하려면 {}를 전송하세요.

정적 속성 규칙

속성 이름에는 ASCII 문자, 숫자, 그리고 _ - . : / # @ 문자가 포함될 수 있으므로, http://schemas.example.com/claims/site 또는 urn:oid:1.3.6.1.4.1.5923.1.1.1.6과 같은 URI 및 OID 이름도 허용됩니다.
각 정적 속성은 하나의 비어 있지 않은 문자열 값을 가집니다.
이름은 서로 또는 어설션 내 사용자 속성 이름과 충돌해서는 안 됩니다: 속성 매핑의 Value name of your application 열에 있는 이름이나, 아무것도 매핑되지 않은 경우 sub, email, name과 충돌해서는 안 됩니다. Logto는 이름을 camel case로 변환한 후 ., _, -를 단어 구분자로 사용하여 비교합니다. 예를 들어, site_id, site.id, SiteId는 충돌하며, account와 Account도 마찬가지입니다. 이 검사는 속성 매핑을 변경할 때도 실행됩니다. 저장 시 충돌이 보고되면, 속성 중 하나의 이름을 변경하세요.

어설션 내 모든 속성(매핑된 속성과 정적 속성)은 urn:oasis:names:tc:SAML:2.0:attrname-format:basic NameFormat을 사용하며, xs:string 값으로 전송됩니다. 서비스 제공자가 urn:oasis:names:tc:SAML:2.0:attrname-format:uri NameFormat의 URI 또는 OID 이름을 기대한다면, basic도 허용하는지 확인하세요.

SAML 속성 이해하기​

Logto에서의 속성 매핑​

일반적으로 사용되는 속성​

정적 속성​

Console에서 정적 속성 구성하기​

Management API로 정적 속성 구성하기​

정적 속성 규칙​