A claim is how a user is represented in a system.
The OpenID Connect (OIDC) and Security Assertion Markup Language (SAML) protocols can send over a claim for a user who has successfully logged in.
- OIDC sends an id_token that contains a JavaScript Object Notation (JSON) object which is made up of custom fields and values that are determined by the identity provider.
- SAML sends an XML assertion. An assertion is usually made up of custom attributes with custom fields and values that are determined by the identity provider.
The claims-based integration:
- is based on the Single Sign-On (SSO) that is set up in your environment.
- uses the claims (that are contained in XML assertions or id_tokens) to create and/or update member records.
- Instead of looking at just the unique identifier, Higher Logic looks at even more fields that represent the user.
NOTE: The claims-based integration can be used in conjunction with the Push API integration. This is necessary if you want to send more fields that are outside of the SSO capability, and is referred to as the SSO-Push hybrid. If you want to use the Push API integration, see Higher Logic Push API Integration (V1).
Requirements
You must have a functioning (OIDC or SAML) SSO set up in your AMS/CRM database.
Member Refresh
The table below shows all the configurable fields for the claims-based integration.
WARNING: Not all fields are configurable with the claims. Additional fields need to use SSO push hybrid.
User Base information
Field | AMS Field | Higher Logic Use |
---|---|---|
Legacy Contact Key | sub claim NameID (or a different custom attribute configurable in SAML) |
This is the unique identifier of the user. This is required for any user.
|
Member Id | Configurable to a field in the claims. | A secondary ID with which it is possible to identify contacts. |
Prefix Code | Configurable to a field in the claims. | A name prefix (e.g., Mr., Mrs., Dr.). |
First Name | Configurable to a field in the claims. | The first name of the user. |
Last Name | Configurable to a field in the claims. | The last name of the user. This is required for any users acting as individuals. |
Suffix | Configurable to a field in the claims. | A name suffix (e.g., Jr., III). |
Designation | Configurable to a field in the claims. | A designation or credential (e.g., CPA). |
Informal Name | Configurable to a field in the claims. | A nickname for the user. |
Gender | Configurable to a field in the claims. | The gender of the user. |
Ethnicity | Configurable to a field in the claims. | The ethnicity of the user. |
Age | Configurable to a field in the claims. | The user’s age. |
Birthday | Configurable to a field in the claims. | The user’s birthday. |
Member Since | Configurable to a field in the claims. | Date the user joined the organization - usually used for Website Alerts. |
Member Expires On | Configurable to a field in the claims. | Date the user's membership expires - usually used for Website Alerts. |
Exclude From Directory | Configurable to a field in the claims. | A boolean field which will opt the user out of showing in the directory. |
Is Member | Configurable to a field in the claims. | A boolean field that determines if a user is granted IsMember privileges when coming over. |
Title | Configurable to a field in the claims. | A job title for the user. |
Company Name | Configurable to a field in the claims. | The name of the company with which the user is associated with. This is required for any users acting as companies. |
Bio | Configurable to a field in the claims. | Biography |
Profile Image URL | Configurable to a field in the claims. | A publicly accessible URL to a profile picture. Images are resized to 200x200. |
Email Address | Configurable to a field in the claims. | The email address of the user. This is required for any user. |
Phone 1 | Configurable to a field in the claims. | Phone number 1 |
Phone 2 | Configurable to a field in the claims. | Phone number 2 |
Phone 3 | Configurable to a field in the claims. | Phone number 3 |
Phone 4 | Configurable to a field in the claims. | Phone number 4 |
Address Line 1 | Configurable to a field in the claims. | Number & street name. |
Address Line 2 | Configurable to a field in the claims. | Apartment or building number. |
Address Line 3 | Configurable to a field in the claims. | Other address info. |
City | Configurable to a field in the claims. | User’s city of residence. |
State | Configurable to a field in the claims. | User’s state of residence. |
Postal Code | Configurable to a field in the claims. | User’s postal code. |
Country | Configurable to a field in the claims. | User’s country. |
Website URL | Configurable to a field in the claims. | Full web site URL. |
Youtube URL | Configurable to a field in the claims. | Full YouTube profile URL. |
Facebook URL | Configurable to a field in the claims. | Full Facebook profile URL. |
Twitter URL | Configurable to a field in the claims. | Full Twitter profile URL. |
LinkedIn URL | Configurable to a field in the claims. | Full LinkedIn Profile or page. |
WordPress URL | Configurable to a field in the claims. | Full WordPress site URL. |
Blogger URL | Configurable to a field in the claims. | Full Blogger site URL. |
Other Blog URL | Configurable to a field in the claims. | Full site URL for other blog. |
Is Organization | Configurable to a field in the claims. | A boolean field which will determine if the user is a company or individual. |
Do Not Email | Configurable to a field in the claims. | A boolean field which will opt the user out of receiving emails from Higher Logic. |
Roles | Configurable to a field in the claims. | Field in claims that specifies security group membership. |
A note about address information
Address info can also come over from the claims.
SAML requires that each address line maps to its own custom attribute. See the following example:
<Attribute Name="addressline1">
<AttributeValue>16761 SE Polk St Suite 49</AttributeValue>
</Attribute>
<Attribute Name="city">
<AttributeValue>Portland</AttributeValue>
</Attribute>
<Attribute Name="state">
<AttributeValue>Or</AttributeValue>
</Attribute>
<Attribute name"zip">
<AttributeValue>97202</AttributeValue>
</Attribute>
OIDC specifies that the address must align with the OIDC specification and must point at a JSON object. See the following example:
“address”:{
“adddressline1”: “16761 SE Polk St Suite 49”,
“city”: ”Portland”,
“state”: ”OR”,
“zip”: “97202”
},…
Company User Base information
Company records are supported. IsOrganization needs to return true. Company name needs to have a value. Please see schema above.
Community Memberships
WARNING: Claims based integration does not support communities. If communities are to be added, they will need to be pushed as part of the standard Push integration.
Security Group Memberships
Integrated Security Groups can only be created from a single claim within the SAML assertion or OIDC id_token. If a member is to be assigned to multiple integrated security groups in the platform that claim must point at a collection of values.
Below is a sample SAML assertion where a member is assigned to three Security Groups: Member, Staff, and Discussion Moderator and the claim containing their group assignments is labeled “groups”.
<Attribute Name="groups">
<AttributeValue>Member</AttributeValue>
<AttributeValue>Staff</AttributeValue>
<AttributeValue>Discussion Moderator</AttributeValue>
</Attribute>
In the context of OIDC, the id_token would look like this:
“groups”: [“Member”, “Staff”, “Discussion Moderator”]
Custom Demographics
WARNING: Claims based integration does not support custom demographics. If additional custom demographics are to be added, they will need to be pushed as part of the standard Push integration.
Periodic Refresh
There is no periodic refresh. Users are updated when they log in or if they are pushed via the push integration as part of the SSO hybrid.
Events Refresh
WARNING: Events do not come over as part of the claims integration. If you would like events, all events would need to be pushed as part of the standard Push integration.
Activity Sync
WARNING: Activity sync is not supported out of the box with the claims integration. You would need to use one of our other generalized activity providers like the Webhook.
FAQ/Common Issues and Solutions
Claims-based refresh
Why is the user not updating properly?
- If the user is not refreshed when logging in it is likely that the attributes are not being mapped correctly from the SSO assertion. One of the fields in the mapping configuration could be incorrect misspelled . Please open a support ticket with Higher Logic and provide the SSO assertion attribute names that you would like to be mapped.
There is a new field that should be added to the integration as a demographic, security group, or community group
- You will need to make sure that the field is included in the SSO assertion, then open a support ticket with Higher Logic to have a mapping added. You will need to provide the assertion attribute name for the field that needs to be integrated so it can be mapped to the HL field.
Can HL change which address is coming over as an Individual’s primary address?
- Yes, HL can map only one address, if it is not displaying the correct address, then this mapping can be updated in the mapping configuration. Please open a support ticket with Higher Logic to have this done.
Can an IsActive flag or an active status be configured to come over?
- No, the claims-based attribute map does not allow mapping an isActive status. (As always, users can be restricted by Security Group)
Push integration (if using hybrid)
There are a few error messages that come from the API layer. Please note that almost all errors are that the JSON is not formatted correctly or the headers are missing or improperly added.
I see that that the request was successful but I don't see any users added to the site or their information updated.
- Check if the refresh server has been enabled. If it is not enabled, the requests will go through but the logic to add to the Higher Logic site will not work. Once the request has been properly parsed, a refresh is queued for that new user. If the refresh server is disabled, this action will not happen and the user will not be added to the site.
- Make sure that each user is sent with a unique LegacyContactKey value within the MemberDetails object.
- Make sure that all required fields are filled out.
Error: Could not process payload.
- This means that the JSON is not in the right format. Please see the first section which outlines what the body should look like.
Error: RequestId: [Guid] Process exited before completing request
- This means that the request was missing the Content-Type header. The header must be set to "application/json".
Error: Could not parse request body into json: Unexpected character (\'}\'
- This means that the Content-Type header was not set to "application/json".
Error: Forbidden
- The api-key header is missing/incorrect. Please make sure the api-key is set to the correct value.