¶ Introduction

The Uber Identity Web SDK supports both authentication to obtain id_token and authorization to obtain access tokens to use with Uber APIs.

Authentication establishes who someone is, and id_token can be used to create a user session or establish link between Uber identity and your user identity. Authorization is the process of granting or rejecting access to data or resources. It includes obtaining and managing user consent, limiting the amount of data or resources shared with scopes, and retrieving an access token for use with Uber APIs.

Web clients can use this library to obtain id_tokens/auth codes or both.

¶ Deciding if the Web SDK is right for you

Web SDK implements:

• Popup based consent flows to minimize redirects, thus enabling users to remain on your site throughout the authentication/authorization process.
• Redirect based flow, obviating need to manage auth requests.
• Security features such as Cross-site Request Forgery (CSRF).

When implementing without the Web SDK you are responsible for:

• Managing requests and responses with Uber’s OAuth 2.0 endpoints, including redirect handler.
• Optimizing the user experience.
• Implementation of security features to validate requests, responses, and to prevent CSRF.

¶ Configure your application

1. Register an application. You will need Client ID from the application dashboard to use SDK.
2. Request for required scopes. Scopes limit the amount of data or resources shared. Profile scope is required for id_token. Other scopes depends on Uber API you are going to use.
3. Allowlist redirect urls for the application. In case of ux_mode=‘popup’, this is the origin of your application where SDK is used. In case of ux_mode=‘redirect’, Uber allows redirect only to these URLs. If this field is not set, users will get an error.
4. Allowlist origin urls for the application. Add the origin domain in Origin URIs. If the field is not set then the browser will not load the token response.

After configuration is complete, take note of the client ID that was created. You will need the client ID to complete the next steps. (A client secret is also created, but you need it only for server-side operations.)

¶ Integrate SDK in your Application

1. Load SDK using a script tag. You can make it async defer. SDK will attach an object UberAPI on the window. window.UberAPI.auth module has two methods init and signin.

<script src=”https://cdn-url-of-sdk.js”  />

2. Initiate the library with config.

authConfig = {
     clientId: String,
     scope: String,
     redirectURI: String,
     nonce:String,
     state: String,
     uxMode: ‘redirect|popup’,
}

UberAPI.auth.init(authConfig)

¶ Config

Name	Type	Description
clientId	string	Your application id created at developer.uber.com
scope	string	scopes you want to request. openid scope is required for id_token
redirectURI	string	redirect url in case of ux mode redirect.
state	string	state will be passed to redirect uri for response validation
nonce	string	it will be included in id_token claims for validation. The nonce parameter value needs to include per-session state and be unguessable to attackers.
uxMode	string	It can be redirect or popup. Default is popup.

3. Invoke signin or requestTokens method on user interaction like button click. It will return a promise which will resolve with auth response.

For Authentication -

UberAPI.auth.signIn().then((response, error) => {
  /*response/error handling logic*/
})}

For Authorization -

UberAPI.auth.requestTokens().then((response, error) => {
  /*response/error handling logic*/
})}

¶ Auth response

Incase of signin -

{
  "id_token": "jwt",
}

Incase of requestTokens -

{
  "access_token": "access_token",
  "token_type": "Bearer",
  "expires_in": 24356788,
}

¶ ID token claims

In addition to mandatory claims, id_token will contain following user profile claims.

{
  "name": "name",
  "email": "xyz@gmail.com",
  "phone_number": "1234567890",
  "picture": "picture"
}

¶ Validating the ID Token

After receiving the token from the signin or the requestTokens method it’s important to parse and validate the token received to make sure the token isn’t compromised and the signature is authentic, this reduces security risks if the token has been tampered, misused or expired. JWT Validation checks its structure, claims and signature to assure the risk is reduced.

For the next steps, we strongly recommend using JWT Libraries for validation and parsing, but there is the option to follow the RFC 7519 and manually implement the validation.

The Token signature is generated using RS256, and you are able to verify it using the response from our certs route (auth.uber.com/oauth/v2/certs) which will provide JWKs which can be transformed into the public key for validating the signature as the following code snippet shows:

  const jwt = require("jwt");
  const jwkToPEM = require("jwk-to-pem")

  UberAPI.auth.requestTokens().then((response, error) => {
    if (error) {
      throw error
    }

    const decodedToken = jwt.decode(response.access_token, {complete: true})
    const kid = decodedToken.headers.kid

    const response = await fetch('https://auth.uber.com/oauth/v2/certs');
    const jwkResponse = await response.json()

    const signatureKey = null
    for (key of jwkResponse.keys) {
      if (key.kid === kid) {
        signatureKey = key
        break
      }
    }

    if (!signatureKey) {
      throw new Error();
    }

    const publicKey = jwkToPEM(signatureKey)
    try {
      const decoded = jwt.verify(token, publicKey);
      console.log(decoded)
    } catch (e) {
      throw new Error();
    }
  })

Besides verifying the token signature, it’s important to check if all the obrigatory claims are correct, following the list:

• iss: The Client ID of the application;
• sub: The Client ID of the application;
• aud: auth.uber.com;
• exp: The expiration time of the JWT;
• jti: An unique identifier for the JWT;
• iat: The time at which the JWT was issued.

And the following headers:

• alg: RS256;
• typ: JWT;
• kid: Key UUID from key file.

¶ Reference

¶ UX modes

The SDK supports two ux modes. These are the user flows for these ux modes.

¶ UX mode - Redirect

1. User clicks Sign in using Uber or Any custom text.
2. Page is redirected to the Uber authorization server.
3. If the user already has an active session with Uber, then the consent page is shown. Otherwise user is asked to signing before consent.
4. Once the user provides consent to give necessary authorization, the user is redirected back to your redirect uri.

¶ UX mode - Popup

1. User clicks ‘Sign in using Uber’ or Any custom text.
2. A popup window is opened which points to the Uber authorization server. Main window remains the same.
3. In the popup window - if the user already has an active session with Uber, then the consent page is shown. Otherwise user is asked to signing before consent.
4. Once the user provides consent to give necessary authorization, the popup is closed and focus is returned back to the main window.

¶ Discovery URL

https://auth.uber.com/.well-known/openid-configuration

¶ Certificates

Use auth.uber.com/oauth/v2/certs to get certificates to read id_token JWT.