Applicable To:
Duke Health
Duke University
Note: Developers may also want to view the Security Offices' position statement on Mobile Application Testing.
IT Security Office position statement:
The purpose of this document is to describe a recommended approach to securely integrating OAuth with native mobile applications at Duke. At a high level this approach requires: a registered OAuth client using the authorization_code grant type, a web application to facilitate OAuth interactions on behalf of the native application, and an API capable of introspecting an OAuth token in order to allow or deny access to resources.
Authentication flow
As soon as the user attempts to do something within the native application that requires Duke user authentication the native application makes a request to the web application along with its unique device identifier in order to request authentication. The web application stores the device’s unique identifier and redirects the user to Duke’s OAuth instance where authentication is facilitated by the standard Shibboleth login web page. Upon successful authentication the user will be asked to grant access to any attributes registered during the OAuth client setup. Next Duke’s OAuth instance sends an authorization code to the web application. The web application calls Duke’s OAuth instance with the authorization code to retrieve the access token and refresh token. The web application securely stores the refresh token and access token and associates these tokens with the device’s unique identifier. The web application redirects back to the native application and sends the access token along with the response. The native application can now use the access token to speak to any API that is capable of introspecting OAuth tokens using Duke’s OAuth introspection endpoint.
The native application can securely store the access token and reuse it for API requests until the access token expires.
If the access token is expired or revoked, the native application makes a request to the web application and includes the expired access token and the device’s unique identifier. If the web application recognizes the access token and device unique identifier it will retrieve the refresh token it has securely stored for this device and request a new access token from Duke’s OAuth instance. If the refresh token is still valid Duke’s OAuth instance will issue a new access token and the flow resumes such that the access token is sent back to the web application and from there it is returned to the native application. If the refresh token is expired the user is prompted to authenticate again and the flow continues.
If the native application user wishes to log out, the native application will send a request to the web application to notify it of the user’s wish to log out and then the native application will delete its own access token. Upon receiving this request, the web application will delete its record of the device’s unique identifier, the latest access token, and the corresponding refresh token. The web application should also call Duke’s OAuth instance’s token revocation endpoint to revoke each token.
Due to the persistence of the access token and refresh token it may sometimes be necessary to require additional device native biometric or PIN verification within the native application. The purpose is to prevent someone other than the owner of the device from accessing sensitive information. For example, if the user hands their unlocked device to a friend or child they do not want this user to have access to the device owner’s sensitive information. Developers should refer to Duke’s Data Classification Standard in order to determine what types of information should require additional user verification.
By following this approach native apps benefit from security and the app works with many features of Duke Identity Providers such as multi-factor authentication, including device-based authentication through Duke Unlock.
Security Offices position statements outline the ISO/ITSO's view on security-related topics and provide guidance concerning Duke standards.
Document Type: Other