Identity provider claims for EWA Multiplatform

EWA Multiplatform (the web edition and the app) signs users in through ClientHub, which in turn signs them in with your OpenID Connect identity provider. After sign-in, EWA Multiplatform reads the user's claims from ClientHub and uses them to create or recognise the user.

This page lists the claims your identity provider must send, what each one is used for, and what goes wrong when one is missing. Configure them before users start signing in, because the claims a user first signs in with decide how that user is recognised later.

For the general OpenID Connect setup of the EWA system, see OpenID Connect Configuration.

Required and recommended claims

Claim	Requirement	Used for	If it is missing
name	Required	The user's display name in EWA.	The user cannot sign in.
preferred_username	Required	The identifier that recognises the same user on every sign-in, so the user keeps their EWA user and everything linked to it.	Sign-in succeeds, but every sign-in creates a new EWA user. Work linked to the previous user, such as personnel assignments, is no longer linked to the person who signs in.
sub	Recommended	The OpenID Connect subject. Used to keep the user's background session working.	Sign-in is not blocked.
email	Optional	Extra user information.	No effect on sign-in.

The claim names must match exactly. EWA Multiplatform does not currently fall back to other claims such as unique_name, upn, given_name or family_name, so an identity provider that sends only those will not work until it also sends name and preferred_username.

Requirements for preferred_username

The value of preferred_username must be:

• Unique: no two users may share a value.
• Stable: the same user must get the same value on every sign-in, on every device, for as long as they use EWA.

Values are compared without regard to upper and lower case, so Ola.Nordmann@example.no and ola.nordmann@example.no are the same user.

Choose the source of this claim before going live. If the source is changed after users have signed in, for example from a login name to an email address, each user gets a new value and EWA treats them as new users.

Configuring common identity providers

The examples below are starting points. Follow your own identity provider's documentation and internal guidelines for the exact steps.

Microsoft Entra ID

• Use the v2.0 endpoints (https://login.microsoftonline.com/{tenant}/v2.0) and request the openid and profile scopes. Tokens from the v2.0 endpoints contain name and preferred_username.
• Tokens from the older v1.0 endpoints contain unique_name and upn instead, and do not work with EWA Multiplatform.
• In Entra ID, preferred_username is normally the user principal name. Make sure the user principal names in your tenant are not reused or renamed for active EWA users.

Active Directory Federation Services (AD FS)

AD FS does not send name or preferred_username unless it is told to. Add issuance transform rules to the relying party for EWA that send:

• the user's display name as name
• a unique, stable login identifier, such as the user principal name, as preferred_username

Keycloak

The built-in profile client scope sends both name and preferred_username. Make sure the profile scope is assigned to the EWA client and that users have a first name and last name set, since Keycloak builds name from them.

Checking the configuration

Before rolling out to users, sign in with a test user and inspect the ID token or the userinfo response in a tool your organisation trusts. Check that:

1. name is present and contains the user's full name.
2. preferred_username is present, and has the same value after signing out and in again.
3. Two different test users get two different preferred_username values.

Troubleshooting

Symptom	Likely cause	What to do
Sign-in fails with "Invalid identity." together with "A user with the same identity already exists."	The identity provider does not send the name claim. The second message is misleading and does not mean the user exists.	Configure the identity provider to send name.
Sign-in works, but the user appears as a new user every time and loses earlier assignments	The identity provider does not send preferred_username, or its value changes between sign-ins.	Configure the identity provider to send a stable preferred_username.
Two people share the same EWA user	preferred_username is not unique, for example because a login name has been reused.	Use a source for preferred_username that is unique per person.

If the problem remains, contact Bliksund support and include the time of the failed sign-in and the list of claim names (not their values) that your identity provider sends.