External Authentication with your Identity Provider

External Authentication flow

The Mariana Tek External Authentication flow should be used within your web applications where you are set up to provide IDP with Oauth2.0 and OpenID Connect compliance.

Overview

What is IDP?

An Identity Provider (IDP) is a system entity that creates, maintains, and manages identity information for principals and also provides authentication services to relying applications. Identity providers offer user authentication as a service. Examples of IDP providers that we have integrated with include Auth0, Okta, and Cognito.

What is Oauth2.0?

OAuth 2.0 is an authorization framework that delegates user authentication to the service provider (auth server) that hosts the user account and authorizes third-party applications to access the user account. OAuth 2.0 supports different authorization flows for the following application types

Web application that renders pages server-side - Express.js or ASP.NET or Django website
Single page web application (SPA) - Javascript
Mobile App - iOS or Android
Server to Server

What is OpenID Connect?

OpenID Connect is an authentication protocol that is built on top of the Oauth2.0 protocol. It allows users to be authenticated by relying parties. OpenID Connect provides additional capabilities in conveying the identity of the user using the application. Clients use OAuth2.0 to request access to an API on a user’s behalf, but nothing in the OAuth2.0 protocol tells the client user information. OpenID Connect enables a client to access information about a user, such as the user's name, email address, birthdate or other profile information.

At a high level, a user follows this external authentication flow into a Mariana Tek product:

From one of Mariana Tek’s customer-facing apps, a user navigates to your login page and clicks Log In for the Mariana Tek product functionality.
Mariana Tek redirects the user to your login page, including all the variables required by the authorization server, either as individual query params or a single URL-encoded next parameter.
The user views your site's login form and enters their sign in credentials for your site. These credentials will correspond to an active Mariana Tek account, which will be created on behalf of the user if necessary.
If your site successfully authenticates the user's credentials, the external authentication flow redirects the user to the Mariana Tek authorization endpoint.
The external authentication flow then redirects the user to Mariana Tek login.
Once the external authentication flow has been configured on the Mariana Tek platform for your site, the user is then additionally redirected to the /custom-client-openid-connect/ endpoint.
A request to the external authorization endpoint is made.
The external authentication flow again redirects the user to your custom login page.
A post-login request is made to the external authorization endpoint for an authorization code.
The authorization code retrieved in step 9 is then sent in a POST request to MT-redirect-uri from step 2. User credentials including email, first name, and last name will be required in the parameter state.
This authorization code is exchanged for an access_token by making a request to the token endpoint.

Once these steps are complete, the access token may be stored and used to authenticate subsequent API requests.

Client Responsibilities

Clients who want to can build their own Identity Provider that conforms to the OpenID Connect standard

The OpenID Connect Authentication Request describes the state request parameter as recommended but Mariana Tek requires this when authenticating to an Identity Provider. The IDP server must properly handle the state parameter.

The following information is required for Mariana Tek to use your authentication service as an IDP.

Client Authentication

Field Name	Data Type	Description
`CUSTOM_CLIENT_OPENID_CONNECT_KEY`	string	The client ID within your external authentication server.
`CUSTOM_CLIENT_OPENID_CONNECT_SECRET`	string	The client secret within your external authentication server.

OpenID Connect Endpoints where {SUBDOMAIN} will reference your authorization server's site

Field Name	Data Type	Description
`CUSTOM_CLIENT_OPENID_CONNECT_AUTHORIZATION_URL`	string	The URL that handles authorization requests within the client-hosted OpenID Connect flow. Might look something like: `https://{SUBDOMAIN}.com/authorize`
`CUSTOM_CLIENT_OPENID_CONNECT_ACCESS_TOKEN_URL`	string	The URL that generates access tokens within the client-hosted OpenID Connect flow. Might look something like: `https://{SUBDOMAIN}.com/oauth/token`
`CUSTOM_CLIENT_OPENID_CONNECT_REVOKE_TOKEN_URL`	string	The URL that revokes access tokens within the client-hosted OpenID Connect flow. Might look something like: `https://{SUBDOMAIN}.com/oauth/revoke`
`CUSTOM_CLIENT_OPENID_CONNECT_USERINFO_URL`	string	The URL that handles requests for additional user info as part of the client-hosted OpenID Connect flow. Might look something like: `https://{SUBDOMAIN}.com/userinfo`
`CUSTOM_CLIENT_OPENID_CONNECT_OIDC_ENDPOINT`	string	The base URL shared by all endpoints within the client-hosted OpenID Connect flow. This value is required because it allows us to autodiscover endpoints within the OIDC specification. Might look something like: `https://{SUBDOMAIN}.com`
`CUSTOM_CLIENT_OPENID_CONNECT_AUTH_SERVER_LOGOUT`	string	The URL that handles logging out of the authorization server. Might look something like `https://{SUBDOMAIN}.com/logout`
`CUSTOM_CLIENT_OPENID_CONNECT_AUTH_SERVER_NEXT_PARAM_KEYWORD`	string	The keyword specific to the auth server that handles directs the user back to login. This value is not optional because it is required for actual logout. Might look something like: 'returnTo' or 'logout_uri'.

Fields you will need from Mariana Tek to provide your authorization server

Field Name	Data Type	Description
`Application Login URI`	string	The authorization server will need to redirect to your application’s login page. This URI needs to point to a route in your application that should redirect to the `/authorize` endpoint.
`Allowed Callback URLs`	string	After the user authenticates the authorization server will only call back to any of these URLs.
`Allowed Logout URLs`	string	A set of URLs that are valid to redirect to after logout from the authorization server.

Step 1: Authorization Redirect

After a user navigates to the login screen on a Mariana Tek customer-facing application and selects the button to log-in, which triggers a request to the Mariana Tek authorization endpoint for an authorization code.

https://{domain}.marianatek.com/o/authorize
         ?client_id={MT_CLIENT_ID}
         &code_challenge={MT_CODE_CHALLENGE}
         &code_challenge_method=S256
         &redirect_uri={MT_REDIRECT_URI}
         &response_type=code
         &scope=read:account
         &state={STATE}

Parameter	Required	Data Type	Description
`MT_CLIENT_ID`	yes	string	The `client_id` credential issued for your application.
`MT_CODE_CHALLENGE`	yes	string	The code_challenge that was generated based on the code_verifier.
`MT_REDIRECT_URI`	yes	string	The URL where users will be sent after successfully logging in. This must be included in the allowed redirects configured for your application.
`STATE`	yes	string	A value that will be returned along with the authorization code in the response and can be used by your app to maintain state between the authorization request and callback. To prevent CSRF attacks, you should verify that the state in the response matches the value provided in this request.

The user will then be redirected to the MT login page:

https://{domain}.marianatek.com/auth/login/
         ?next={MT_AUTHORIZATION_URL}

Parameter	Data Type	Description
`MT_AUTHORIZATION_URL`	string	The URL from step 1 `/o/authorize` with additional parameters included

Step 2: Custom Client Authentication Flow

After Step 1 has been completed successfully, the user will be sent to the /custom-client-openid-connect/ endpoint to continue the authentication flow. The URL for this endpoint will look like:

https://{domain}.marianatek.com/login/custom-client-openid-connect/
         ?next={MT_AUTHORIZATION_URL}

Parameter	Data Type	Description
`MT_AUTHORIZATION_URL`	string	The URL from step 1 `/o/authorize` with additional parameters included

Next, the code will be requested from the third party external authorization endpoint that will look something like:

https://{SUBDOMAIN}.authserver.com/authorize
         ?client_id={EXTERNAL_CLIENT_ID}
         &redirect_uri=https://{domain}.marianatek.com/complete/custom-client-openid-connect/
         &state={STATE}
         &response_type=code
         &nonce={NONCE}
         &code_challenge={CODE_CHALLENGE}
         &code_challenge_method=S256
         &scope=openid+profile+email

Parameter	Data Type	Description
`EXTERNAL_CLIENT_ID`	string	The`CUSTOM_CLIENT_OPENID_CONNECT_KEY` provided by the authorization server
`STATE`	string	A value that will be returned along with the authorization code in the response and can be used by your app to maintain state between the authorization request and callback. To prevent CSRF attacks, you should verify that the state in the response matches the value provided in this request.
`NONCE`	string	A case sensitive string value used to associate a Client session with an ID Token, and to mitigate replay attacks.
`CODE_CHALLENGE`	string	The code challenge that was generated based on the code_challenge_method (we recommend always using `S256`)

The user will then be redirected back to your login site URL. This is the page where the user will enter their credentials. That URL will look something like this:

https://{SUBDOMAIN}.authserver.com/u/login?state={STATE}

The code will then be requested from the external authorization endpoint (external IDP to external IDP) with a URL that looks something like:

https://{SUBDOMAIN}.authserver.com/authorize/resume?state={STATE}

Step 3: Token Request

Now that you have an authorization code from the external authorization endpoint ({EXTERNAL_IDP_AUTHORIZATION_CODE}), you will be redirected to the /custom-client-openid-connect/ endpoint to retrieve an authorization code from Mariana Tek. This URL will look like:

https://{domain}.marianatek.com/complete/custom-client-openid-connect/
         ?code={EXTERNAL_IDP_AUTHORIZATION_CODE}
         &state={STATE}

{STATE} will need to contain the user credentials to retrieve or create a Mariana User. If a Mariana Tek account that matches the provided email address is not found in our system, a Mariana Tek user account will automatically be created for the user. The required fields are as follows with example json below:

Parameter	Required	Data Type	Description
`email`	yes	string	Email is required for MT accounts.
`given name`	yes	string	The first name of the user.
`family name`	yes	string	The last name of the user.
`name`	yes	string	The first and last name of the user separated by a space character
`home location`	no	dict	This corresponds to the studio that the customer will most often interact with.
`phone number`	no	string	Phone number of the user
`birth date`	no	string	Birth date of the user
`signed_waiver`	no	boolean	Boolean dictating if the user has agreed to Waiver
`marketing_opt_in`	no	boolean	Boolean dictating if the user has agreed to marketing emails
`is_opted_in_to_sms`	no	boolean	Boolean dictating if the user has agreed to marketing via phone number (phone number will be required if True)

Name must contain at least two names separated by a space character. home_location must be a valid Mariana Tek Location ID. Example decoded JWT for the idtoken of specific user data format requirement:

{

'home_location': {'id': 1234},
'birth_date': '02-02-2002', 
'phone': 1234567890,
'name': 'Jane Doe',
'family_name': 'Doe',
'given_name': 'Jane',
'signed_waiver': 'True',
'is_opted_in_to_sms': 'False',
'marketing_opt_in': 'True',
'email': 'marianatek@xplortechnologies.com'

}

You will receive another authorization code that will be sent via a POST request to the Mariana Tek authorization endpoint that will look like:

https://{domain}.marianatek.com/admin/auth
         ?code={MT_AUTHORIZATION_CODE}
         &state={STATE}

Finally, the authorization code can be exchanged for an access token that can be used to make authenticated requests with Mariana Tek APIs. This request can be constructed from the following parameters:

POST https://{SUBDOMAIN}.marianatek.com/o/token

The request will look like:

{
         'code': {MT_AUTHORIZATION_CODE},
         'code_verifier': {MT_CODE_VERIFIER},
         'redirect_uri': {MT_REDIRECT_URI},
         'client_id': {MT_CLIENT_ID}
}

Parameter	Required	Data Type	Description
`MT_AUTHORIZATION_CODE`	yes	string	The authorization code obtained from the Mariana Tek authorization endpoint.
`MT_CODE_VERIFIER`	yes	string	Randomly generated string to verify code challenge
`MT_REDIRECT_URI`	yes	string	The URL provided as part of step 1. If your app only has one `redirect_uri` configured, that value is used as a default.
`MT_CLIENT_ID`	yes	string	The `client_id` credential issued for your application.

The response will look like this:

{
         'access_token': {MT_ACCESS_TOKEN},
         'expires_in': 604800,
         'token_type': "Bearer",
         'scope': "read:account",
         'refresh_token': {MT_REFRESH_TOKEN}
}

Parameter	Data Type	Description
`MT_ACCESS_TOKEN`	string	The access token used in requests to Mariana Tek API.
`MT_REFRESH_TOKEN`	string	The refresh_token that can be exchanged for a new access_token.

Login page guidelines on your application

Login page must be mobile friendly and for all mobile applications you will need to create an account in your IDP platform for the specific App Review account so that Apple and Google can review the app after submission. Additionally, an account for Mariana Tek will also be required for testing of these applications.

iOS

Applications that exclusively use a third-party or social login service (such as Facebook Login, Google Sign-In, Sign in with Twitter, Sign In with LinkedIn, Login with Amazon, or WeChat Login) to set up or authenticate the user's primary account with the app must also offer Sign in with Apple as an equivalent option. These application login pages will also need to be Apple compliant.

Android

Please see this link for guidelines on complying with the Android process.

Setting up employee accounts

The IDP flow creates standard user accounts for new employees when they create an account using the flow. In order to establish an employee account in Mariana Tek, including a specific role(s), permissions, and turf, the steps below must be followed: A separate employee creates a regular customer account if needed for the new employee. An employee with the relevant permission to create new employee accounts will login to the Admin product and enter the email of the new user account in the New Employee section for the field 'Email' and hits the tab button. This will auto-populate user account information and the employee creating account will need to manually set remaining required fields such as locations that employee can interact with, Role, among other required fields.

Webhooks

You can use webhooks to receive notifications about particular events in Mariana's platform. There will be specific webhooks sent around this process that you can subscribe to. The client will need to be subscribed in order to listen and receive the webhook alert. Visit our page on Webhooks for more information

profile.created

If a Mariana Tek user account is created in the flow of external auth, a webhook for profile.created will be sent.

profile.updated

If Mariana Tek receives a field change to a user account, there is an optional webhook to reflect the changes between what is received via the external authentication flow and what Mariana Tek has on record. This would include the following fields:

Parameter	Required	Data Type	Description
`email`	yes	string	User email is required for MT accounts.
`first name`	yes	string	The first name of the user.
`last name`	yes	string	The last name of the user.
`home location`	no	int	This corresponds to the id of the Mariana Tek Location studio that the customer will most often interact with.
`phone number`	no	string	Phone number of the user
`birth date`	no	string	Birth date of the user
`is_external_user`	no	boolean	A boolean value reflecting if the user has been associated with the IDP

This webhook will also be sent if the user account has been archived and you will need to update your records of that user's account.

External Authentication flow#

Overview#

What is IDP?#

What is Oauth2.0?#

What is OpenID Connect?#

At a high level, a user follows this external authentication flow into a Mariana Tek product:#

Client Responsibilities#

Client Authentication#

OpenID Connect Endpoints where {SUBDOMAIN} will reference your authorization server's site#

Fields you will need from Mariana Tek to provide your authorization server#

Step 1: Authorization Redirect#

Step 2: Custom Client Authentication Flow#

Step 3: Token Request#

Login page guidelines on your application#

iOS#

Android#

Setting up employee accounts#

Webhooks#

profile.created#

profile.updated#