Identity Federation
Identity federation lets an OEM's users sign in to Consumer Services with the account they already have at the OEM, instead of creating a separate username and password. The OEM keeps ownership of authentication, and Consumer Services maps each federated user to a single Consumer Services user.
This page gives a high-level overview of how federation works and what is involved in connecting an OEM. Federation is set up in cooperation with Telenor; it is not self-service.
How it works
Consumer Services uses an Amazon Cognito user pool for end-user authentication. The OEM's identity provider (IdP) is registered in that user pool as an external identity provider. When a user chooses to sign in with the OEM, they are sent to the OEM's IdP, authenticate there, and are redirected back with an authorization code that is exchanged for Consumer Services tokens.
Account linking
A user is identified by their email address. When a user signs in through an OEM for the first time:
- If a Consumer Services user with the same email already exists, the OEM identity is linked to it. The user ends up with a single account, whether they sign in natively or through the OEM.
- If no such user exists, one is created automatically and the OEM identity is linked to it. The user is confirmed automatically and no verification or welcome email is sent.
Because linking is based on email, the OEM's IdP must return a verified email address for every user. The tokens issued by Consumer Services contain the same userId regardless of which way the user signed in, so downstream APIs (such as E-commerce) behave identically for federated and native users.
Things to be aware of
- Mapped attributes are refreshed from the OEM's IdP on every sign-in.
- Users who sign in through federation are subject to the same consent and KYC requirements as native users.
Setting up federation for an OEM
Prerequisites
The OEM needs an identity provider that supports OpenID Connect (OIDC), with a publicly reachable discovery document (/.well-known/openid-configuration). The IdP must be able to return, at least, the claims email, email_verified and, preferably, locale.
Steps
-
Agree on scope. Contact Telenor support to discuss which environments (stage, production) and which brand or application the federation is for. Federation is enabled per environment.
-
Register Consumer Services at your IdP. Create an OIDC client (application) in your IdP using the authorization code flow, and register the Consumer Services redirect URI for each environment:
https://consumer-services-{environment}.auth.eu-north-1.amazoncognito.com/oauth2/idpresponseTelenor support will confirm the exact URI to use. Request the scopes
openid email profile. -
Share the connection details with Telenor. Send the following through a secure channel agreed with support (never by plain email):
- The issuer URL (
oidc_issuer) of your IdP. - The client ID and client secret of the OIDC client.
- A short, unique provider name for your IdP, such as
acme. It is used to identify your users' sign-in option and as the prefix of linked identities, so it cannot be changed later. - How your IdP names the email,
email_verifiedand locale claims, if they differ from the standard names.
- The issuer URL (
-
Telenor registers the identity provider. The IdP is added to the Consumer Services user pool with an attribute mapping from your claims, and enabled for the Consumer Services application client. This is rolled out to stage first, and then to production once you have verified it.
-
Test in stage. Sign in with a test user from your IdP and verify that:
- the sign-in redirects to your IdP and back,
- a Consumer Services user is created, or linked if a user with the same email exists,
- the access token contains the expected
userId.
-
Go live. After a successful test in stage, Telenor enables the provider in production. Your application can then start a sign-in with your provider name.
Starting a federated sign-in
Once the provider is enabled, an application starts a sign-in by sending the user to the authorization endpoint of Consumer Services with identity_provider set to your provider name, using the authorization code flow. Contact support for the Consumer Services domain, client ID and redirect URIs that apply to your application.
# Open in the user's browser
https://consumer-services-{environment}.auth.eu-north-1.amazoncognito.com/oauth2/authorize\
?response_type=code\
&client_id=your-client-id\
&redirect_uri=https%3A%2F%2Fyour-app.example.com%2Fauth%2Fcallback\
&scope=openid+email+profile\
&identity_provider=your-provider-name
The application then exchanges the returned code for tokens at the token endpoint:
curl -X POST \
https://consumer-services-{environment}.auth.eu-north-1.amazoncognito.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "client_id=your-client-id" \
-d "code=authorization-code-from-redirect" \
-d "redirect_uri=https://your-app.example.com/auth/callback"
The access token from the response is used as a Bearer token towards the API, as described under Authentication.
Maintenance
Tell Telenor support ahead of time if your IdP changes in a way that affects the integration, for example when rotating the client secret, changing the issuer URL or changing the claims returned.