How to call Azure Active Directory B2C¶

We use Azure Active Directory B2C as an identity management service and standard OAuth2. This page describes how you can integrate this service into your application and retrieve the needed tokens. The retrieved access token needs to be set as the Authorization request header. The value needs to include the Bearer schema at the beginning of the token value e.g.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...

If the application already has created a guest token with the profile service and the user authentication is done later then the account should be merged with the B2C profile. For more details check merge profiles.

Currently, the following authentication options were enabled:

username / password (local discover.swiss account)
Microsoft
Google
Apple ID

Info

We can add more identity providers. Contact our support if you have specific requirements.

Integration¶

Info

Before you can use the authentication service we need to register an application for you in our tenant. This can't be done in the developer portal. Please contact us via support@discover.swiss and we'll start the onboarding process with you.

The following parameter needs to be send in the Azure B2C call:

policy name
client-Id (you get it when we register your application)
redirect url (we need to register all you redirect URLs in the application we've created for you. Please let us know all needed URLs. If you're using a different redirect URL then the Azure B2C call will fail)
(optional) logo: If you specify the logo query parameter then the specific logo will be loaded instead of the partner logo. You need to provide the logo to us.

Partner acronym is resolved based on your client-Id. With it your partner logo will be loaded and a relationship between the user and you is created

example url

https://login.discover.swiss/ccdd9a47-e6f8-46a4-a0f0-d406f370bd20/oauth2/v2.0/authorize?p={flow-name}&client_id={clientId}&nonce=defaultNonce&redirect_uri={redirect-url}&scope=openid&response_type=id_token&prompt=login

The demo portal demonstrates the usage of Azure B2C in an Angular SPA. Detail information about Azure B2C in the integration options can be found in the official Azure Active Directory B2C documentation from Microsoft. The documentation from microsoft includes examples how you can integrate it e.g. Tutorial: Enable authentication in a single-page application using Azure Active Directory B2C

Scopes¶

In the Azure B2C calls the following scopes should be provided:

ClientId: You need to pass your specific client id
offline_access: With the offline_access scope a refresh token will be returned too
openid: With the openid scope an ID Token will be returned too

Warning

Before using the integration productively, an acceptance meeting must be held with us. It is also important to switch to the productive application registration and use the prod policies as well as the productive profile service.

Policies¶

The policy specifies the behavior of the user flow. The policy needs to be passed as a query parameter or in the URL path:

Tip

For the test environment flows add _test to the name of all available flows e.g. b2c_1a_signup_signin_test. On the Environment page, all the available flows were explicitly listed per environment.

In this table, the available policies were listed.

Purpose	Name	Remark
sign up - sign in	b2c_1a_signup_signin	Default flow which allows sign-in and sign-up of users.
sign up - sign in popup	b2c_1a_signup_signin_popup	Same flow as b2c_1a_signup_signin but it doesn't show the cancel buttons. This can be useful if flows are opened in a popup window.
sign in	b2c_1a_signin	A flow that provides only login but no sign-up. Will return an error if a user tries to login with a social account that does not exist already with an error message that the user needs to sign up first.
reset password	b2c_1a_passwordReset	Reset the password in case the user registered with username/password. This is offered inside the sign-in process so you do not need to place it explicitly.

Token & Claims¶

We only collect few information on the sign up process.

Email address
Given name
Surname
Terms & Conditions

The display name will be automatically set by joining the given name and surname. The terms & conditions will be dynamically loaded based on the partner acronym. If you have terms & conditions which should be shown then you need to provide them to us.

Claims¶

Provided claims which can be used. Your app should not rely on other claims.

claim	description
name	Display name
given_name	Users given name
family_name	Users family name
acr	Name of the B2C policy which was used to issue the token
oid	The unique Azure B2C user object id
profileId	The id of the discover.swiss profile
ds_roles	Contains a list of discover.swiss roles separated by comma

{
    "acr": "b2c_1a_signup_signin",
    "name": "Corinne Eiger",
    "given_name": "Corinne",
    "family_name": "Eiger",
    "oid": "9749fccb-00cc-4d91-b9ea-fbee8c37de09",
    "ds_profileId": "a0bb2c3c-5cd0-4b06-aa8f-de8b1f100214",
    "ds_roles": [
        "ds_pp|ds",
        "hotelier|log_px9-s28_bfihed"
    ],
}

Account / ID matching¶

Multiple sign-in options can be added to the user. You should not statically map the user based on the email address to internal systems because the user could change the sign-in name. You should store and rely on the profileId.

Email address¶

The email address returned in the token should not be used to contact the user per email. It's only the username provided by the user. With the login, the user has not automatically granted the permission to contact him via email. This needs to be defined in the terms and conditions. The email address stored in the email property of the profile should be used as correspondence email.

Token lifetime¶

The refresh token can be retrieved if your application had been granted the offline_access scope.

Access and ID token lifetime: 60 minutes
Refresh token lifetime: 14 days
Refresh token sliding window lifetime: 90 days

The policy b2c_1a_token_expiration_test can be used to test the token behavior. This policy is configured against the test environment. For this test policy the lifetime for the Access and ID token is 5 min. The refresh token has a lifetime of 1 day and the rolling refresh token lifetime is 2 days.

UI¶

The standard sign-in interface look like this:

discover.swiss signup / sign in

Logo¶

The partner logo is shown in the top bar. You need to provide us this logo during the onboarding process of this service.

The logo will be loaded in the following priority:

logo query parameter
partner acronym resolved by your client-id

Language¶

The interface is available in the following languages:

de
en
fr
it

The language is determined in the following order:

ui_locales query parameter: With the query parameter ui_locales the language can be specified e.g. "ui_locales=de"
Browser-requested language: If no ui_locales query parameter was specified, your user flow is translated to the browser-requested language, if the language is supported.
Policy default language: If the browser doesn't specify a language, or it specifies one that is not supported, the user flow is translated to the user flow default language.

Customization¶

If you have specific requirements please contact our support.

The Email address, surname and given name can be passed to the sign up flow by setting them in specific query parameters. This should be done if this information is already collected from the user so that the user doesn't need to provide the same information again in the sign up process.

property	query parameter
email address	prefillEmail
given name	prefillGivenName
surname	prefillFamilyName

Verification of Authorization tokens¶

In case you need to verify the token when accessing your own API (authorization):

Server side

The authorization token is a standard JWT and validation can be done with all JWT libraries. Important to know is that the used keys change regularly. There are libraries from Microsoft and the handling of the key is already built in.

This article is helpful (see Validation): Overview of tokens in Azure Active Directory B2C

And this is the url to get the keys:

https://login.discover.swiss/ccdd9a47-e6f8-46a4-a0f0-d406f370bd20/discovery/v2.0/keys?p=b2c_1a_signup_signin

(where the name of the flow - p - should be the one you use to authenticate)

The JSON document located at this URL contains all the public key information in use at a particular moment. Your app can use the kid claim in the JWT header to select the public key in the JSON document that is used to sign a particular token. It can then perform signature validation by using the correct public key and the indicated algorithm.

Here you can download all links and resources (including the one above).

https://login.discover.swiss/ccdd9a47-e6f8-46a4-a0f0-d406f370bd20/discovery/v2.0/.well-known/openid-configuration?p=b2c_1a_signup_signin

Logout¶

GET https://login.discover.swiss/ccdd9a47-e6f8-46a4-a0f0-d406f370bd20/{sign up-sign in flow name}/oauth2/v2.0//logout?post_logout_redirect_uri={redirect-url}

With calling the logout from Azure B2C the client gets logged out on the Identity provider. If you do not call this, the user is automatically logged in again when the sign-in flow is called before the session on Azure B2C times out. Therefore to allow to switch users you must call the logout on your application logout.

more information: Send a sign-out request

Local account password policy¶

The password for a local account has the following requirements:

The password must be between 8 and 64 characters.
The password must have at least 3 of the following:
- A lowercase letter
- An uppercase letter
- A digit
- A symbol