The USTA API uses AWS Cognito as an identity provider organized using the OAuth2 access model. Web and mobile applications interact with Cognito using https
Grant Types
Applications can use one of two OAuth2 grant types:
Authorization Code used for browser applications where the user authenticates as themself.
Client Credentials used for server-side applications where the service authenticates as the service and establishes a session.
Credentials
After discussion with the USTA API team, USTA will issue credentials for the appropriate grant type to the application developers.
Important Consideration
Due to AWS Simple Email Services constraints, it is imperative that you use real email addresses for registration and forgot password testing scenarios. Emails that cannot be delivered (considered a bounce) will count against the SES bounce score. When too many bounces are received in a 24 hour period, Amazon will suspend the operation of the USTA SES instance. This notice applies to registration and forgot password scenarios.
Please register using a valid email
Please use a real email when performing forgot password
USTA’s implementation of Cognito introduces a 2 step registration process (Cognito Native and Lightweight Account Registration). Due to limitations with customizing the Cognito Hosted Registration page, the approach taken is to break up registration into two steps.
Note: Step 2 of the registration process must be completed within one hour. Accounts created in Cognito that have not been completed within one hour will be deleted.
The proposed UX flow would work in the following way:
UX Flow
Client Public Page - User visits USTA.com, clicks on the login link
Cognito Hosted Login - Gets redirected to Hosted Login Page, clicks on sign up
Cognito Hosted Registration - Gets redirected to Hosted Registration, Enters Email and Password
USTA Lightweight Registration Page - Gets redirected to the lightweight registration page, completes the registration
Client Secure Landing Page - Gets redirected to logged in secure landing page
Registration Process Flow
Sequence Diagrams
Please refer to the sequence diagrams for the technical flow
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'
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
Step 3: Get Auth Code returned from the previous step
When valid credentials are provided then the browser is redirected to {callbackUri} with code={authorizationCode} param in the url
Step 4: Call to /token with Auth Code to obtain tokens (Access, Refresh)
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}
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: 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 usta.com domain as cookie collisions can occur and may be overwritten in unexpected ways.
Step 5: Check if Lightweight Registration was completed
Option 1: You may check for the existence of the “uaid” key in the ID token. If this field exists and is populated, then the hybris profile exists and the Light Weight Registration was already completed. More information can be found here.
Option 2:
Call /customers/me endpoint and check validation errors:
Customers can create a USTA profile there, by filling-out basic, mandatory data. When a customer clicks the “Register” button and all data is valid then the browser is redirected back to the passed redirectUri and access_token can be used against services.
The Lightweight registration screen will perform USTA validations including duplicate account check as part of its functionality.
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 jwt.io. This is a valuable debugging tool.
