Zephr User Guide

Third Party Authentication

4 views 0

Zephr allows you to use OAuth 2 to log in to third-party apps using Zephr login details.

This allows third-party apps to access user identity information and profile information, or to update a user’s data.

This follows the OAuth 2.0 Authorization Code Grant as described here.

Configuration

This flow requires some configuration in the Third Party Authentication area of your Site Configuration, as well as calls made to the Zephr APIs.

Navigate to Delivery > Sites and then select the relevant site from the menu.

Scroll down and select Third Party Authentication. Here, select the Enable OAuth 2.0 toggle.

In the Allowed Origins section, enter the origin from which the user would call the OAuth 2.0 Authorization Server. For example, if the user would be logging in, using Zephr credentials, from Google, this may be
https://www.google.com/login.

In the Redirect URIs section, enter the third-party URL the user will be redirected to whenever the authorization has been granted, or an error has occurred.

The OAuth Page Customization section allows you to include a Logo, Login Page Title, Consent Page Title, Identifier Placeholder and Background Color.

These will be used on the login and consent pages, created by Zephr, to gain authorization and consent from the user logging in.

The following images show how these fields are used:

OAuth 2.0 - Page Customisation 1 OAuth 2.0 - Page Customisation 2

The pages created will ask a user to log in if they have not already done so.

The user will then be asked to consent to the third party application the grant requested. The scope of the grant can be user.account:read, user.profile:read or user.profile:update.

Once configured, click Done, then save your Site Settings.

Getting the User Token

By clicking on the Allow button (pictured above) the user is redirected to the redirect URI of the request with an authorization code that can later be exchanged for an access token.

If you click on the developer tools and inspect the network call you are then shown the authorisation code, which should be used to make your first API call:

OAuth 2.0 - Authorisation Code

The token exchange endpoint call is on the admin console and must be done using Basic Authorization, using the Client ID and Client Secret displayed in the Third Party Authentication section of your Site Configuration (once you have enabled OAuth 2.0).

The payload needs to contain the Authorization Code and Redirect URI used, as well as the Grant Type field as shown below.

curl --location --request POST
'https://console.zephr.com/zephr/oauth2/token' \
--header 'Authorization: Basic
ZzQya3R1dXl5cHE5Om12dty2x3bXJycGgwNW95YjBzdmVud2V0OQ==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "code": "kcpa10fzqa9nmut95duwok0c",
    "redirect_uri": "https://thirdparyurl.com/auth/callback",
    "grant_type": "authorization_code"
        }'

Here is an example successful response body of the token exchange request:

{
    "scope": "user.account:read, user.profile:read",
    "access_token": "oa_rrcly8rsusfc1e5sdgxzv8uh",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "1if5j2aaverj80tx2nvvvutq",
    "user_id": "68c0f5ae-f857-408f-a9d6-f511df0f8ae8"
}

With the information in the response body, you then need to take the access token and make a second API call as below using bearer token authentication to get/update the user information. Details for this can be found in the Public API Documentation.

Finally, as the access token expires, if you require another access token for that user, you can use the following API call, which includes the refresh_token that you previously obtained.

This will give you a new access token for that user with the same scope.

curl --location --request POST
'https://console.zephr.com/zephr/oauth2/token' \
--header 'Authorization: Basic
ZzQya3R1dXl5cHE5Om12d2x3bXJycGgwNW95YjBzdmVud2V0OQ==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "refresh_token": "1if5j2aaverj80tx2nvvvutq",
    "grant_type": "refresh_token"
        }'