USTA’s implementation of Cognito redirects the user to the Cognito Hosted Login Page (Cognito Native Login). When the user signs in for the first time, we employ a just in time migration strategy. Users are presented with the ability to Sign Up (create a new account) or Sign In with an existing account.
It is the responsibility of the Secure Client page to check if the user’s lightweight profile is completed. If it is not, the user will be redirected to the lightweight profile screen until the required fields are filled out and saved.
Note: Janrain has been deprecated as of 2022.
Approach
Before you begin the development of your browser-based application, contact USTA to discuss what data you will need to access from USTA. Credentials will be issued for use to connect via HTTP.
Credentials:
client id
client secret
USTA Admin will register your application as a client in the Cognito configuration.
When the token for the authorized customer is needed Client API application needs to follow typical OAuth 2.0 flow using authorization code grant type. To perform such flow Client API should be registered in the USTA authentication service and should have valid:
clientId - generated for every API Client during registration
secret - generated for every API Client during registration
callbackUri - an endpoint where authorization code will be passed after successful login - should be configured for all clients
state - a random generated value such as UUID to prevent CSRF attacks. ie '29ca0dd4-966d-400d-9abc-570568f5c339'
To perform login as a customer, API Client application should follow such steps:
Client App redirect to login or authorize URLs:
https://stage-account.usta.com/login - can be used if the customer should be asked if want to continue as current logged in user before authentication.
https://stage-account.usta.com/oauth2/authorize - can be used if application should NOT ask the customer if they want to continue as a current, logged-in user (from SSO session) - user will be logged-in automatically if SSO session is in place with url parameters:
client_id={clientId} - mandatory, for example: 25idmdru0ucur4loa3hklcvpsa
response_type=code - mandatory
scope={requested scopes} - optional, if empty, all required scopes will be assigned to the token
state - a random generated value such as UUID to prevent CSRF attacks. ie '29ca0dd4-966d-400d-9abc-570568f5c339'
redirect_uri={callbackUri} - mandatory, for example:
This occurs when the /login endpoint is called while an existing SSO session is currently active. In this case, the client is not challenged to reenter credentials. If they choose to Sign In as <XXXXXXX> then the session established from the prior login challenge will be used.
After redirection customer can sign in or sign up using the email address and password or Facebook account:
Add Logic to Client Secure Landing Page
When valid credentials are provided then the browser is redirected to {callbackUri} with code={authorizationCode} param in the url
The {callbackUri} endpoint request should start obtaining the token process by calling POST: https://stage-account.usta.com/oauth2/token endpoint with such params (by x-www-form-urlencoded format):
client_id = {clientId}
redirect_uri = {redirectUri}
code = {authorizationCode}
grant_type = authorization_code
and by passing API Client credentials by standard Basic Authentication header: Base64encoded: {clientId}:{secret}
access_token - JWT token for accessing USTA APIs/services - valid for 1h:
refresh_token - special, log-life token for refreshing id and access tokens - valid for 30 days, cannot be refreshed
Client endpoint should save tokens for future usage: id_token, access_token - can be saved in the secure browser space, for example, cookies, local storage and can be used for calling USTA APIs/services, should be never passed by URL params. refresh_token - can be saved on the server-side in session or other safe storage, must not be passed to the browser
USTA recommends naming cookies based on the client id. Cookies should also be stored on the subdomain level (i.e. subdomain.usta.com). Cookies should not be stored on http://usta.com domain as cookie collisions can occur and may be overwritten in unexpected ways.
Working with JWT Tokens
JWT tokens are encrypted JSON format and contain fields called claims. Once you generate an Access Token, you can examine the contents at http://jwt.io . This is a valuable debugging tool.
Dont Make the User Type In Credentials Again
With OAuth2 application developers often make the mistake of retrieving an Access Token before each API call. This is not efficient. Instead, use the long lived Refresh Token that is supplied with the short-lived Access Token when the Authentication Code is exchanged for the Access Token. Use the Refresh Token to rerequest another Access Token without making the user type in their credentials again.
Request:
Response:
Check For 401 Status Response To Determine Whether To Use Refresh Token
One simple way t deterine if the Access Token has expired is to check each API call for a 401 status in the response. In this case, use the Refresh Token to get a new short-lived Access Token without additional authentication.
Keep Track Of Expiration Time To Live
A more involved method is to track the expiration TTL when you retrieve your Access Token. If the time has expired, then use the Refresh Token to get a new short-lived Access Token and repeat the API call with the new Access Token.
