Isode OAuth

Isode Provisioning with OAuth

This section introduces OAuth by showing how users and OAuth permissions are provisioned using Isode’s Cobalt tool. The screenshot below shows a provisioned user:

User provisioning will usually include the means to authenticate the user, such as password and/or certificate.

As part of the provisioning, OAuth permissions can also be configured:

This deployment has three Isode applications configured – two are Red/Black servers and one is Icon-5066. Cobalt allows one or more (application-specific) permissions to be configured for each application instance. These permissions could reflect anything, but for these products they reflect roles (permission groups) that the user is allowed to adopt.

The OAuth framework provides an approach to assign application permissions to users of Web applications.

Why OAuth?

There are a number of reasons for using OAuth to provide the services described in this paper:

1. It is a widely used service in support of authentication and authorization of Web applications.
2. It operates so that user credentials are never shared with a Web application using OAuth. This is a highly desirable security characteristic.
3. An authorization framework can be provided that is common to all of the Web applications.
4. Authentication is decoupled from the Web applications. This means that authentication improvements (e.g., two factor authentication) can be provided in one place and then shared by all of the applications.
5. Single Sign On between OAuth enabled applications is straightforward to achieve.

OAuth 2.0

OAuth is used in this paper to refer to the OAuth 2.0 family of specifications and associated standards. These are widely documented and this is not repeated here.

OAuth can be used in a number of ways. An example often used in the OAuth literature is control of a photo printing application’s access to stored photos. OAuth is often described in the context of this sort of application.

A widely deployed and familiar use of OAuth is for Web sites that offer the choice to use third party authentication (e.g. Google authentication) to access the site or services. The user's credentials are validated by Google and never shared with the original Web site.

Isode is using OAuth in the specific manner described in this paper. The focus is to use OAuth to effectively support Isode Web-managed Applications, rather than to provide a generic OAuth capability that might be used for a different class of problem.

Isode Web Application Use of OAuth

The following diagram summarizes the interaction needed between user, browser, Web application and OAuth server. In OAuth terminology, the Isode Web Application is both the OAuth client and the protected resource. 

There are a number of interactions when a User authenticates to an Isode Web Application using OAuth, shown in the diagram above. Although there are many steps, the core function is that the Web Application redirects the user to authenticate to the OAuth server and then the OAuth server provides a Token and associated information to the application. The detailed steps are as follows.

1. User chooses to connect to Isode Web Application and directs the browser to the correct URL.
2. The browser connects to the Web application. The Web application determines that this session is not authorized.
3. The Web Application passes the browser a URL for the OAuth server (authorization endpoint).
4. The browser connects to the OAuth server.
5. The OAuth server returns a form, requesting credentials from the user.  
6. The browser presents the form for the user to fill in.
7. User fills in the form.
8. Browser sends completed form to the OAuth server. OAuth server validates the user based on this information and generates a reference to a potential Token.
9. OAuth server sends the newly created reference to the browser. Note that for security reasons, a Token is never passed to the browser.
10. Browser passes the reference to the Web application.
11. Web application connects to OAuth server (token endpoint) providing the reference. OAuth server validates Web application, using either the Client Secret or the X.509 Client signature. The latter provides better security and is recommended. At this point, the Token is created.
12. OAuth server sends Token to Web application. Note that the Token is opaque to the Web application.
13. Web application uses the Token to request information from the OAuth server (Userinfo endpoint). This may be done in multiple iterations. Typical information requested:
1. Information on identity of end user, typically used for logging and display back to the user.
2. Permissions for the user for the Web application. This controls the rights that the user is given.
14. Information requested is provided. Web application now knows the user’s rights.
15. Web application can now start sending application information to browser.
16. Application information sent to user, who can now start using the application.

The key results of this interaction is that the Web application has validated the user and determined user rights, with the authentication happening between user and OAuth server without involvement of the Web application.

OAuth Tokens

The Isode Web Application gets two tokens from the OAuth server, each of which has an expiry time. The first is an Access Token. The Web application will only provide service to the user while the Access Token is valid. The Refresh Token, which will have a longer life than the Access Token, can be used by the Web Application to get a new Access Token from the OAuth server.

Once the Refresh Token has expired, the user must re-authenticate. So the Refresh Token duration determines how frequently a user needs to re-authenticate. When the Web Application requests a new Access Token, the OAuth server will re-validate the user’s rights. So Access Token duration determines how responsive the application will be to changes in user rights.

Isode's OAuth server has configurable default times for these tokens. This can be overridden as part of the Cobalt configuration of each Isode Web Application (OAuth client) as shown below.

Isode M-Vault OAuth Server

Isode's OAuth server is a part of M-Vault. Tight integration with M-Vault enables direct access to user and application information stored in M-Vault. It uses this information:

1. To manage OAuth configuration.
2. To read information on OAuth Clients (Isode Web Applications).
3. To authenticate users.
4. To get information on users needed by the OAuth Clients.
5. To get information on user permissions for OAuth Clients.

Note that OAuth Permissions are stored as directory attributes in the user’s entry, representing string values associated with clients. The OAuth server provides the clients with permissions (strings) for that client only through the Userinfo endpoint.

The configuration of an OAuth server in M-Vault is managed by Cobalt, as shown below:

Cobalt also configures location of users and OAuth Clients in the directory. Cobalt configures OAuth Clients, as show below:

Note that the Client Secret is stored as a hash in the directory, so that the OAuth server can validate it, but the secret is not exposed.

User Authentication

The OAuth Server authenticates the end user. M-Vault provides two mechanisms to do this:

1. Username/Password. Here a web form is provided to the browser, where the user fills in usernae and password, which the diretory checks.
2. Windows Single Sign On (SSO). This uses Kerberos based Windows enterprise logon to validate the user. It means that a user signed on to Windows will be able to access OAuth applications without presenting additional credentials. The Windows ID is mapped to a user entry in M-Vault.

Use with Non-Isode Web Applications

The infrastructure described here was developed initially to support Isode's own Web applications. Use of OAuth by a Web application is relatively straightforward. Isode's OAuth infrastructure provides a means of provisioning users, user rights and applications. This can be used to support third party applications.

Conclusions

This whitepaper has given an overview of OAuth and how Isode provides OAuth in its product set. Isode plans to extend OAuth capbilities and to make wider use of OAuth in the Isode product set.