SSO flow for native applications

This topic describes the single sign-on (SSO) flow for native applications, such as mobile applications. For information on the SSO flow for web-server applications, see SSO flow for web server applications.

Special security considerations apply to native applications when using the authorization code flow. RFC 8252 - OAuth 2.0 for Native Apps was created to define best practices for such cases. These best practices include RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE), an extension to the core OAuth 2.0 specification that secures the authorization code flow when used in native applications.

AppDirect conforms to both RFC 8252 and RFC 7636.

AppDirect recommends the use of AppAuth client SDK to simplify integration with native applications and ensure best practices are followed.

This section describes the OpenID Connect SSO flow for native applications integrated with an AppDirect-powered marketplace. A description of each step follows the image.


1. The user begins the single sign-on (SSO) transaction within the native application by, for example, entering their username and clicking on a login button.
2. The Developer generates a cryptographically random _code\_verifier_ and associated _code\_challenge_:
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
   Next, the Developer looks up the user’s OIDC configuration, opens a browser, and initiates SSO by sending a request to the authorization endpoint and including the code_challenge_method and code_challenge query parameters (required for PKCE).

Following is an example of how it appears:
https://marketplace.exampletelco.com/oauth2/authorize?response_type=code

&scope=openid profile email  
&client_id=s6BhdRkqt3&state=af0ifjsldkj  
&code_challenge_method=S256  
&code_challenge=FULBvRhW7stRYdJC2WQ1Tar4QtmoKtArNR6H-cnAGXg  
&redirect_uri=com.isv.mobileapp:/callback

3. The user is authenticated with the marketplace.
4. An authorization code is returned to the redirect_uri passed in step 2. Note: this URI must also match one of the values entered in the Redirect URL configuration field on the Edit Authentication page.

Following is an example:
com.isv.mobileapp:/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj5

5. The Developer sends a POST request to the token endpoint to exchange the authorization code for the ID and access tokens. The request includes the code\_verifier generated in step 2.

curl -X POST "https://marketplace.exampletelco.com/oauth2/token?grant_type=authorization_code&code=AYo3IQ&&code_verifier=rtDJlZb3hnHD0P65DYiUF0Xmplzg_anBoflHNGq0yCM&redirect_uri=com.isv.mobileapp:/callback"

6. The AppDirect authorization server transforms the code\_verifier using the following method:
   BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) = transformed_code_verifier The authorization server then authenticates the request by ensuring the transformed\_code\_verifier matches the code\_challenge passed in step 2. After the request is verified, the ID, access and refresh tokens are returned in the response (see Token Response Example E in the OpenID Connect authentication event examples topic).
7. The ID token is validated by the Developer, including the signature. See Signature verification and key rotation to learn more and see the OpenID Connect specifications for details on token validation.
8. The Developer retrieves additional user data (first/last name, email, etc.) from the User Info endpoint. This is a regular API call that requires the access token returned in step 6 to be included as a bearer token.
   curl -H 'Authorization: Bearer <access_token>' https://marketplace.exampletelco.com/oauth2/userinfo
9. The user data is returned
10. The user is logged in to the Developer application.