Skip to main content

Security Guidelines

TODO

The following provides you information to ensure your integration with SeniorSign is secure.

Transport Layer Security (TLS)​

To prevent man-in-the-middle attacks, all communication must be done using Transport Layer Security (TLS). Your customer must validate the SeniorSign TLS Certificate.

Request Confidentiality​

The items listed below must never be transmitted in the clear:

  • Access tokens
  • Resource Owner Passwords
  • Client credentials
  • Authorization codes The state parameters must not include sensitive client or resource owner information in plain text because they can be transmitted over insecure channels or not stored securely. For more information, see The OAuth 2.0 Authorization Framework section 10.8.

Cross Site Request Forgery (CSRF)​

Preventing Cross Site Request Forgery (CSRF) attacks helps protect the security of your users. A CSRF attack against the client's redirection URI allows an attacker to inject its own authorization code or access token, which can result in the client using an access token associated with the attacker's protected resources rather than the victim's. For more information, see The OAuth 2.0 Authorization Framework section 10.12.

The SeniorSign authorization server supports the state parameter as the means to counter CSRF attacks. The first step is creating a unique state parameter value. It is recommended to make this value a string a minimum of 30 characters using a secure random-number generator. The state parameter is sent with the first leg of the OAuth flow as part of the authorization request. Later, in your back-end server, you must confirm that the state received from SeniorSign matches the value you created and sent in the authorization request. This round-trip verification helps to ensure that the user, not a malicious script, is making the request.

The generated state value can then be stored either in the cookie or, more appropriately, in the session and used subsequently to perform the check as explained earlier.

Public Client Applications​

At this time SeniorSign does not support public client applications. Public clients are defined as clients incapable of maintaining the confidentiality of their credentials (for example, clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application). For more information, see The OAuth 2.0 Authorization Framework section 2.1.

It is important to understand that for a native application, even if the client_secret is somehow hidden in the compiled code or obfuscated, it must not be considered as a secret. An attacker can reverse engineer the code to obtain the secret.

You can use mobile native applications as long as they are paired with a back-end server. The client secret is stored on the server in backend storage and communicated only over a secure HTTPs channel so it is not leaked. In this case, your mobile application acts like the front end of a web application and the OAuth authorization code exchange for access token happens in the back-end server.

Note:

At this time SeniorSign is evaluating the usage of PKCE without a client secret as a way to use OAuth with a public application.

User Agents and Phishing Attacks​

A WebView and/or iframe is not an acceptable means of opening the SeniorSign login page and will be blocked in future releases of SeniorSign. WebViews and/or iframes don’t show the trust indicators present in the system web browser. For example, SSL/TLS lock indicating certificate chain validation and the URL of the site. This results in users being more vulnerable to phishing attacks by malicious applications.

Users have greater security assurances with the system web browser because they are used to the typical security indicators, such as the SSL/TLS lock and the URL of the site. This makes users less vulnerable to phishing.

Depending on your platform, It is recommended to open the SeniorSign login (authorization) page using 1 of the following:

  • For an iOS app, use an SFSafariViewController
  • For an Android app, use a Chrome Custom tab
  • For a Web-based applications, redirect the same browser window to the authorization page or open a new browser tab or window

For the mobile use cases, these methods open a full-page browser with limited navigation capabilities. They appear inside a host app that retains the full security properties and authentication state of the system browser.

Service providers should attempt to educate end-users about the risks phishing attacks pose and should provide mechanisms that make it easy for end-users to confirm the authenticity of their applications. End-user should learn to verify the authenticity of the SeniorSign login page where they are entering their credentials, such as the SSL/TLS lock indicating certificate chain validation and the URL of the site. For more information, see OAuth 2.0 for Native Apps.

Token Storage​

Treat access token and refresh token as passwords and apply industry best practices to storing passwords securely sever-side and mobile side.

SeniorSign recommends you store the OAuth related tokens in your back-end server and proxy calls to SeniorSign through it rather than storing the tokens on the mobile device.

If you must store tokens on the mobile device, you should only store the access token. Refresh tokens have a longer lifetime than access tokens and can be used to generate additional access tokens if it is compromised. Refresh tokens are usually subject to strict storage requirements to ensure they are not leaked.

Depending on your platform, It is recommended to store access tokens using 1 of the following:

  • For an iOS app, store your access token in the Keychain
  • For an Android app, store your access token in SharedPreferences

It is recommended to securely store the access token encrypted (the key used to encrypt the token must not be discoverable) and to delete the token after the user logs out of the application and/or the session expires. If a device gets rooted, it is possible for an attacker to steal tokens stored in the KeyChain and/or SharedPreferences. It is strongly recommended to not store tokens on the mobile device. Keep them in-memory only, and when the application is closed, they are automatically cleaned up.

Note:

The next time the application is launched, the user must re-authenticate to obtain new tokens.

In addition, do not place the tokens into audit logs or other ledgers where a third party could later surreptitiously look for them. For password storage best practices, see the Password Storage Cheat Sheet.

Mobile Security​

SeniorSign recommends you follow industry standard best practices to secure your mobile application. For more information, see the OWASP Mobile Top 10 and the OAuth 2.0 for Native Apps.