Users can login to your applications using the MOTAR SSO which will have full CAC support in Summer 2021
To authenticate a MOTAR user in a 3rd party app, you will need to follow the MOTAR OAuth flow. Before beginning this process, you will need to have an app created with a client ID and secret, as well as a registered redirect UI in MOTAR Studio.
If your app is a standalone web client, you can use MOTAR's OAuth flow to render a login screen in a web client. Note that if you're app is launched from the MOTAR Dashboard, you should authenticate using a redirect auth code. If your app is not launched from the MOTAR Dashboard and you cannot render a webview, you can use Basic Auth.
First, display a MOTAR auth screen to the user. Use your client ID to identify your application to the user and enter the URI you wish the auth screen to redirect the user to upon auth completion.
In response to the authorization request, a web page login form for MOTAR is displayed. The user logs in and decides whether or not to allow to your app. After the user decides, MOTAR will redirect to the redirect URI provided in the initial request.
In the case of a failed login or denial of permissions, an error is returned:
GET <REDIRECT_URI>?error="User cancelled request."
Your application should be configured to handle these parameters.
Next, your application should use the AUTH_CODE from the redirect above to generate an auth token to use with the MOTAR API.
The response from MOTAR will be in the following JSON format:
- access_token - the MOTAR access token to use in API calls. Use this token in the "Authorization" header as follows:
Authorization: Bearer <ACCESS_TOKEN>. The access token uniquely identifies the logged in user and your app on the MOTAR platform.
- refresh_token - once the access token expires, the web server application can retrieve a new one with the refresh token (see below).
- expires_in - length of life for the access token before it must be refreshed (see below).
After this step is complete, the user is officially logged into the MOTAR platform and can use the API as normal using their access token.
When the access token expires (defined by the expires_in field), it must be refreshed for the user to continue to use the API.
Make a call to the token URL to refresh an access token (production):
For security reasons, the MOTAR API uses a relatively short access token life of 24 hours. Since access tokens only a short period of time, your app will need to refresh them to maintain usability. There are generally two strategies for determining when to refresh a token.
With this strategy, your app will need to keep track of when the access token was generated, and perform a refresh before this timer expires. This is the preferred method, as it reduces the chances of retry errors.
Alternately, apps can automatically refresh an access token when the API indicates that the token has expired. The API will return the following when a client attempts to use an expired token:
"error_description": "Token refresh required",
At this point, the client should pause its request, refresh the access token, and then retry with the refreshed access token.