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 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 shows all the configurable fields for the claims-based integration.

NOTE: Not all fields are configurable with the claims. Additional fields have to use SSO-Push hybrid.

User Base information

A note about address information

Address information can also come over from the claims.

• SAML requires that each address line maps to its own custom attribute:

<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 requires that the address aligns with the OIDC specification and points at a JSON object:

“address”:{
    “adddressline1”: “16761 SE Polk St Suite 49”,
    “city”: ”Portland”,
    “state”: ”OR”,
    “zip”: “97202”
},…

Company User Base information

Company records are supported.

• IsOrganization must return true.
• Company Name must have a value.

See schema above.

Community Memberships

The Claims-based integration does not support communities.

• If you want to add communities, they must be pushed as part of the standard Push API integration.

Security Group Memberships

Integrated Security Groups can be created only 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 OIDC, the id_token would look like this:

“groups”: [“Member”, “Staff”, “Discussion Moderator”]

Custom Demographics

The Claims-based integration does not support custom demographics.

• If you want to add additional custom demographics, they must be pushed as part of the standard Push API integration.

Periodic Refresh

There is no periodic refresh.

Users are updated when they log in or if they are pushed via the Push API integration as part of the SSO-Push hybrid.

Events Refresh

The Claims-based integration does not support events refresh.

• If you want to add events, they must be pushed as part of the standard Push API integration.

Activity Sync

The Claims-based integration does not support activity sync. You have to use one of our generalized activity providers like the Webhook.

FAQs and troubleshooting

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 correctly mapping from the SSO assertion. One of the fields in the mapping configuration could be misspelled. Create a case and provide the SSO assertion attribute names that you would like mapped.

A new field should be added to the integration as a demographic, a security group, or a community group

• Make sure that the field is included in the SSO assertion, then create a case to have a mapping added. Provide the assertion attribute name for the field to be integrated so it can be mapped to the field in Higher Logic.

Can Higher Logic change which address comes over as a primary address?

• Yes, Higher Logic can map only one address. If it is not displaying the correct address, then this mapping can be updated in the mapping configuration. Create a case 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 API integration (if using hybrid)

There are a few error messages that come from the API layer. Note that almost all errors are that the JSON is not correctly formatted or the headers are missing or are 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 completed.

Error: Could not process payload.

• The JSON is not in the right format. Refer to the first section which outlines what the body should look like.

Error: RequestId: [Guid] Process exited before completing request

• 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 (\'}\'

• The Content-Type header was not set to "application/json".

Error: Forbidden

• The api-key header is missing/incorrect. Make sure the api-key is set to the correct value.