Requirements

1. VTS sandbox app for testing
2. VTS provided Client ID, Example: izgmCHvK9Wqu3SipGdf8ldfjglsjflgjdlgjueyi
3. VTS Auth0 Domain: auth.vts.com
4. {if using custom claims} ext-integration-id in Redirect URL which is specifically for custom claims (this is passed as query parameters in the redirect URL)
5. VTS public keys: https://auth.vts.com/.well-known/jwks.json

If you do not have the required items above please refer to section Getting Started section to get the required items above

Supported Claims

Standard Claims

🚧

VTS does not support separate first name and last name in app.

{  
  "mobile": null,  
  "tenant_id": "04ae2415-dd9f-4cb6-adce-890ac5865cfc",  
  "tenant": "Cumin Kitchen",  
  "building_id": "3a2f38f2-60ac-4317-8578-9710d99d799f",  
  "building": "Sita Manhattan",  
  "given_name": "Bob Marley",  
  "family_name": "-",  
  "nickname": "Bob Marley",  
  "name": "[[email protected]](mailto:[email protected])",  
  "picture": "<https://s.gravatar.com/avatar/f11364efcbeab43e1c9c944d20056a09?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fiv.png">,  
  "updated_at": "2024-09-30T20:17:30.495Z",  
  "email": "[[email protected]](mailto:[email protected])",  
  "email_verified": true,  
  "iss": "<https://viewthespace-stg.us.auth0.com/">,  
  "aud": "ers4RLxx8RPNKG1INJhz5mEHjg4f9js6",  
  "iat": 1727727676,  
  "exp": 1743497676,  
  "sub": "auth0|903f5ae4-9f78-4ab5-88a9-f2ca15a41a86",  
  "sid": "pJ0msdwEKsHu4xtuubazL7paqiTAiRlw",  
  "nonce": "fasrwjM4R0pFVm5Rb2w1RUhZSTNYM0ZLN0JMNU5+R2xlZm9pTkVYLWplZA=="  
}

Note: "picture" is currently not the actually link to the user's profile picture in app but a generated avatar based on name and should not be used

Custom Claims

🚧

Using custom claims will require using the redirect URL flow outlined in the docs

Any static alphanumeric value(s) can be added as custom claims today. ex

Samples libraries for React and JS

Auth0 supports libraries for OIDC workflows outlined below and could help accelerate partners looking to support this standard

1. React: https://auth0.com/docs/libraries/auth0-react
2. JS: https://auth0.com/docs/quickstart/spa/vanillajs

VTS OIDC Code Flow

📘

VTS supports Authorization Code Flow with the PKCE approach.

Given that the user has already signed into VTS Activate (the identity provider), the user can access service provider resources simply by navigating to a VTS Activate URL that redirects to the service provider service URL.

Steps taken by the VTS app

VTS Activate will handle the initial redirect request during steps 1 and 2.

VTS Identity Provider will verify the user's identity during steps 5 and 6 and return the JWT access token at the end of the authentication process.

Steps taken by 3rd Party

Once the VTS Activate user is redirected to a third-party Provider, the service should identify that the request came in from VTS Activate and engage this OIDC flow to authenticate the request.

Step 3. The provider creates a cryptographically random code_verifier and generates a code_challenge from this Code examples of using PCKE are available here. The verifier must be stored for later use.

Step 4. The third-party Service must redirect the user to the VTS Identity provider (use authorizationendpoint in OIDC configuration shared by the VTS team) along with the code challenge and ext-integration-id that is added to the redirectURL as a query param._Note: This has to be implemented using custom logic built by the third-party but only required when using custom claims

Step 7. The user is redirected to the third-party service’s callback URL, with a single-use authorization code. The callback URL must be on a pre-configured whitelist on the VTS end. Note: This must be the same callback URL configured by the third-party under Activate’s integrations.

Step 8. The third-party service sends the authorization code and the code_verifier (created in step 3) to the token_endpoint in the OIDC configuration.

Step 10. VTS Identity Provider responds with an ID token and access token. After the final step, the third-party performs the JWT token validation using the Auth0 SDK or a Third-Party Library using the VTS identity provider public keys available here.