OAuth

The Security.OAuth package defines and implements the OAuth 2.0 authorization framework as defined by the IETF working group in RFC 6749: The OAuth 2.0 Authorization Framework.

OAuth Client

The Security.OAuth.Clients package implements the client OAuth 2.0 authorization.

Application setup

For an OAuth2 client application to authenticate, it must be registered on the server and the server provides the following information:

  • client_id: the client identifier is a unique string that identifies the application.
  • client_secret the client secret is a secret shared between the server and the client application. The client secret is optional.

The Security.OAuth.Clients.Application tagged record is the primary type that allows to perform one of the OAuth 2.0 authorization flows. It is necessary to declare an Application instance and register the client_id, the client_secret and the authorisation URLs to connect to the server.

App : Security.OAuth.Clients.Application;
...
   App.Set_Application_Identifier ("app-identifier");
   App.Set_Application_Secret ("app-secret");
   App.Set_Provider_URL ("https://graph.facebook.com/oauth/access_token");

Resource Owner Password Credentials Grant

The RFC 6749: 4.3. Resource Owner Password Credentials Grant allows to authorize an application by using the user's name and password. This is the simplest OAuth flow but because it requires to know the user's name and password, it is not recommended and not supported by several servers. To use this authorization, the application will use the Request_Token procedure and will give the user's name, password and the scope of permissions. When the authorization succeeds, a Grant_Type token object is returned.

Token  : Security.OAuth.Clients.Grant_Type;
...
  App.Request_Token ("admin", "admin", "scope", Token);

Refreshing an access token

An access token has an expiration date and a new access token must be asked by using the refresh token. When the access token has expired, the grant token object can be refreshed to retrieve a new access token by using the Refresh_Token procedure. The scope of permissions can also be passed.

 App.Refresh_Token ("scope", Token);

OAuth Server

OAuth server side is provided by the Security.OAuth.Servers package. This package allows to implement the authorization framework described in RFC 6749 "The OAuth 2.0 Authorization Framework".

The authorization method produces a Grant_Type object that contains the result of the grant (successful or denied). It is the responsibility of the caller to format the result in JSON/XML and return it to the client.

Three important operations are defined for the OAuth 2.0 framework. They will be used in the following order:

Authorize is used to obtain an authorization request. This operation is optional in the OAuth 2.0 framework since some authorization method directly return the access token. This operation is used by the "Authorization Code Grant" and the "Implicit Grant".

Token is used to get the access token and optional refresh token. Each time it is called, a new token is generated.

Authenticate is used for the API request to verify the access token and authenticate the API call. This operation can be called several times with the same token until the token is revoked or it has expired.

Several grant types are supported.

Application Manager

The application manager maintains the repository of applications which are known by the server and which can request authorization. Each application is identified by a client identifier (represented by the client_id request parameter). The application defines the authorization methods which are allowed as well as the parameters to control and drive the authorization. This includes the redirection URI, the application secret, the expiration delay for the access token.

The application manager is implemented by the application server and it must implement the Application_Manager interface with the Find_Application method. The Find_Application is one of the first call made during the authenticate and token generation phases.

Resource Owner Password Credentials Grant

The password grant is one of the easiest grant method to understand but it is also one of the less secure. In this grant method, the username and user password are passed in the request parameter together with the application client identifier. The realm verifies the username and password and when they are correct it generates the access token with an optional refresh token. The realm also returns in the grant the user principal that identifies the user.

Realm : Security.OAuth.Servers.Auth_Manager;
Grant : Security.OAuth.Servers.Grant_Type;
  Realm.Token (Params, Grant);

Accessing Protected Resources

When accessing a protected resource, the API implementation will use the Authenticate operation to verify the access token and get a security principal. The security principal will identify the resource owner as well as the application that is doing the call.

 Realm : Security.OAuth.Servers.Auth_Manager;
 Grant : Security.OAuth.Servers.Grant_Type;
 Token : String := ...;
   Realm.Authenticate (Token, Grant);

When a security principal is returned, the access token was validated and the request is granted for the application.