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

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.