Configuring attributes for the userinfo endpoint and ID token for OAuth clients
As a SaaS administrator, you can configure a custom userinfo endpoint or ID token payload by mapping the attributes extracted from an IdP request to custom claims in a user info or ID token response. The responses contain claim values set for specified attributes. An attribute is specified for the user info endpoint or the ID token setting, and is used to search for a value in a session record stored in the database. The attributes are extracted during the authentication phase from the corresponding IdP and stored in the BMC Helix SSO session. Currently, only SAML IdP attribute extraction is supported. The format in which this attribute will be recorded in the database is predetermined in the Name field of the User attributes settings of SAML authentication.
For more information about attribute extraction from SAML IdP, see Configuring-advanced-functions-for-SAML-authentication.
By default, the endpoint response contains the following claims:
- userinfo — sub, name, and tenant
- ID token — name, jti, aud, iss, iat, exp, and sub
If no mapped attributes are found in the session, the endpoint response will contain default payload claims.
The configuration is a three-step process: Select the feature flag for the tenant, set up the User attributes for the realm, and add the claim attributes for the endpoint.
Before you begin
Configure a realm in BMC Helix SSO.
For more information, see Configuring-advanced-functions-for-SAML-authentication.
To configure the tenant and realm for an endpoint
- In BMC Helix SSO Admin Console, click Realm and select the realm to edit.
- Select Authentication, and then select SAML from the Authentication Type list.
- In User attributes, click Add and specify the following fields:
- Name—A name for the extracted attributes.
- XPath—The rule for searching attributes in the SAML request XML.
6. Click Save.
To add the attributes for the endpoint
- Navigate to the OAuth2>Clients.
- Open a client configuration for editing.
Specify the following fields:
For userinfo endpoint
In the Additional attributes for user info table, specify the following fields:
- Claim—A value for the attribute name that will be a part of the user endpoint response.
- Attribute—A name for the extracted attributes. It should correspond to the Name of User attribute in the Realm configuration.
For ID token endpoint
In the Additional attributes for ID token table, specify the following fields:
- Claim—A value for the attribute name that will be a part of the ID token response.
- Attribute—A name for the extracted attributes. It should correspond to the Name of User attribute in the Realm configuration.
- Click Save.
Examples
userinfo
Values configured:
- User attribute extracted based on the mappings defined in the realm: "group": "[a1,b1]"
- Additional attributes set for userinfo endpoint: Claim: GROUPS", Attribute:"group"
Based on the example, the userinfo response will contain the following extracted attributes:
"name": "John Doe",
"sub": "jDoe",
"tenant": "bmc",
"GROUPS": ["a1", "b1"]
}
id_tokens
The following example represents the values included in the default id token response:
"name": "John Doe",
"jti": "4738fb81-5149-48e2-9ab9-991b1aa01e13",
"aud": "d0fde156-2657-44werew4b-ab5d-9c95d1a21ff7",
"iss": "https://rsso.bmc.com/rsso",
"iat": 1705661564,
"exp": 1705665164,
"sub": "jDoe"
}
Values configured:
- User attribute set for SAML authentication: "group": "[a1,b1]"
- Additional attributes set for id_token endpoint: Claim: GROUPS", Attribute:"group"
When you map Groups claim, the id_token contains the following extracted attributes:
"name": "John Doe",
"jti": "4738fb81-5149-48e2-9ab9-991b1aa01e13",
"aud": "d0fde156-2657-44werew4b-ab5d-9c95d1a21ff7",
"iss": "https://rsso.bmc.com/rsso",
"iat": 1705661564,
"exp": 1705665164,
"sub": "jDoe",
"GROUPS": ["a1", "b1"]
}