Oz is a web authorization protocol based on industry best practices. Oz combines the Hawk authentication protocol with the Iron encryption protocol to provide a simple to use and secure solution for granting and authenticating third-party access to an API on behalf of a user or an application.
Protocol version: 1.0.0
- Protocol
- API
- Shared objects
Oz.clientOz.endpointsOz.hawkOz.scopeOz.serverOz.ticket- Ticket options
ticket.issue(app, grant, encryptionPassword, options, callback)ticket.reissue(parentTicket, grant, encryptionPassword, options, callback)ticket.rsvp(app, grant, encryptionPassword, options, callback)ticket.generate(ticket, encryptionPassword, options, callback)ticket.parse(id, encryptionPassword, options, callback)
Oz builds on the well-understood concepts behind the OAuth protocol. While the terminology has been updated to reflect the common terms used today when building applications with third-party access, the overall architecture is the same. This document assumes the reader is familiar with the OAuth 1.0a protocol workflow.
- The application uses its previously issued Hawk credentials to authenticate with the server and request an application ticket. If valid, the server issues an application ticket.
- The application directs the user to grant it authorization by providing the user with its application identifier. The user authenticates with the server, reviews the authorization grant and its scope, and if approved the server returns an rsvp.
- The user returns to the application with the rsvp which the application uses to request a new user-specific ticket. If valid, the server returns a new ticket.
- The application uses the user-ticket to access the user's protected resources.
Oz is an application-to-server authorization protocol. This means credentials are issued only to applications, not to users. The method through which users authenticate is outside the scope of this protocol.
The application represents a third-party accessing protected resource on the server. This third-party can be another server, a native app, a single-page-app, or any other application using web resources. The protected resources can be under the control of the application itself or under the control of a user who grants the application access.
Each application definition includes:
id- a unique application identifier.scope- the default application scope.delegate- iftrue, the application is allowed to delegate a ticket to another application. Defaults tofalse.
Applications must be registered with the server prior to using Oz. The method through which applications register is outside the scope of this protocol. When an application registers, it is issued a set of Hawk credentials. The application uses these credentials to obtain an Oz ticket.
The application Hawk credentials include:
id- the unique application identifier.key- a shared secret used to authenticate.algorithm- the HMAC algorithm used to authenticate (e.g. HMAC-SHA256).
The Hawk protocol supports two Oz-specific header attributes
which are used for authenticating Oz applications (app and dlg).
Applications act on behalf of users. Users are usually people with protected resources on the server who would like to use the application to access those protected resources. For the purpose of the Oz protocol, each user must have a unique identifier which is used by the protocol to record access rights. The method through which users are registered, authenticated, and managed is beyond the scope of this protocol.
An Oz ticket is a set of Hawk credentials used by the application to access protected resources. Just like any other Hawk credentials, the ticket includes:
id- a unique identifier for the authorized access.key- a shared secret used to authenticate.algorithm- the HMAC algorithm used to authenticate (e.g. HMAC-SHA256).
However, unlike most Hawk credential identifiers, the Oz identifier is an encoded Iron string which when decoded contains:
exp- ticket expiration time in milliseconds since 1/1/1970.app- the application id the ticket was issued to.user- the user id if the ticket represents access to user resources. If no user id is included, the ticket allows the application access to the application own resources only.scope- the ticket scope. Defaults to[]if no scope is specified.delegate- iffalse, the ticket cannot be delegated regardless of the application permissions. Defaults totruewhich means use the application permissions to delegate.grant- ifuseris set, includes the grant identifier referencing the authorization granted by the user to the application. Can be a unique identifier or string encoding the grant information as long as the server is able to parse the information later.dlg- if the ticket is the result of access delegation, the application id of the delegating application.ext- custom server data where:public- also made available to the application when the ticket is sent back.private- available only within the encoded ticket.
When a ticket is generated and sent to the application by the server, the response includes all of
the above properties with the exception of ext which is included but only with the content of
ext.public if present.
The ticket expiration can be shorter than the grant expiration in which case, the application can reissue the ticket. This provides the ability to limit the time credentials are valid but allowing grants to have longer lifetime.
When tickets are reissued, they can be constrained to less scope or duration, and can also be issued to another application for access delegation.
A grant is the authorization given to an application by a user to access the user's protected resources. Grants can be persisted in a database (usually to support revocation) or can be self describing (using an encoded identifier). Each grant contains:
id- the grant identifier, allowing the server to retrieve or recreate the grant information.exp- authorization expiration time in milliseconds since 1/1/1970.user- the user id who the user who authorized access.scope- the authorized scope. Defaults to the application scope if no scope is specified.
Scope is an array of strings, each represents an implementation-specific permission on the server.
Each scope string adds additional permissions to the application (i.e. ['a', 'b'] grants the
application access to both the 'a' and 'b' rights, individually).
Each application has a default scope which is included in the tickets issued to the application unless the grant specifies a subset of the application scope. Applications cannot be granted scopes not present in their default set.
When the user authorizes the application access request, the server issues an rsvp which is an encoded string containing the application identifier, the grant identifier, and an expiration.
The Oz public API is offered as a full toolkit to implement the protocol as-is or to modify it to
fit custom security needs. Most implementations will only need to use the endpoints functions
methods and the ticket.rsvp() method
directly.
An object describing an application where:
id- the application identifier.scope- an array with the default application scope.delegate- iftrue, the application is allowed to delegate a ticket to another application. Defaults tofalse.key- the shared secret used to authenticate.algorithm- the HMAC algorithm used to authenticate (e.g. HMAC-SHA256).
An object describing a user grant where:
id- the grant identifier.app- the application identifier.user- the user identifier.exp- grant expiration time in milliseconds since 1/1/1970.scope- an array with the scope granted by the user to the application.
An object describing a ticket and its public properties:
id- the ticket identifier used for making authenticated Hawk requests.key- a shared secret used to authenticate.algorithm- the HMAC algorithm used to authenticate (e.g. HMAC-SHA256).exp- ticket expiration time in milliseconds since 1/1/1970.app- the application id the ticket was issued to.user- the user id if the ticket represents access to user resources. If no user id is included, the ticket allows the application access to the application own resources only.scope- the ticket scope. Defaults to[]if no scope is specified.grant- ifuseris set, includes the grant identifier referencing the authorization granted by the user to the application. Can be a unique identifier or string encoding the grant information as long as the server is able to parse the information later.delegate- iffalse, the ticket cannot be delegated regardless of the application permissions. Defaults totruewhich means use the application permissions to delegate.dlg- if the ticket is the result of access delegation, the application id of the delegating application.ext- custom server public data attached to the ticket.
Utilities used for making authenticated Oz requests.
A convenience utility to generate the application Hawk request authorization header for making authenticated Oz requests where:
uri- the request URI.method- the request HTTP method.ticket- the authorization ticket.options- additional HawkHawk.client.header()options.
The endpoint methods provide a complete HTTP request handler implementation which is designed to be plugged into an HTTP framework such as hapi. The scarecrow plugin provides an example of how these methods integrate with an existing server implementation.
Each endpoint method accepts a set of options.
A required string used to generate the ticket encryption key. Must be kept confidential. The string must be the same across all Oz methods and deployments in order to allow the server to parse and generate compatible encoded strings.
The encryptionPassword value is passed directly to the Iron
module which supports additional inputs for pre-generated encryption and integrity keys as well as
password rotation.
The application lookup method using the signature function(id, next) where:
id- the application identifier being requested.next- the callback method used to return the requested application using the signaturefunction(err, app)where:err- an error condition.app- an application object.
The grant lookup method using the signature function(id, next) where:
id- the grant identifier being requested.next- the callback method used to return the requested grant using the signaturefunction(err, grant, ext)where:err- an error condition.grant- a grant object.ext- an object used to include custom server data in the ticket and response where:public- an object which is included in the response underticket.extand in the encoded ticket asticket.ext.public.private- an object which is included only in the encoded ticket asticket.ext.private.
Authenticates an application request and if valid, issues an application ticket where:
req- the node HTTP server request object.payload- this argument is ignored and is defined only to keep the endpoint method signature consistent with the other endpoints.options- protocol configuration options where:encryptionPassword- required.loadAppFunc- required.ticket- optional ticket options used for parsing and issuance.hawk- optional Hawk configuration object. Defaults to the Hawk defaults.
callback- the method used to return the request result with signaturefunction(err, ticket)where:err- an error condition.ticket- a ticket response object.
Reissue an existing ticket (the ticket used to authenticate the request) where:
req- the node HTTP server request object.payload- The HTTP request payload fully parsed into an object with the following optional keys:issueTo- a different application identifier than the one of the current application. Used to delegate access between applications. Defaults to the current application.scope- an array of scope strings which must be a subset of the ticket's granted scope. Defaults to the original ticket scope.
options- protocol configuration options where:encryptionPassword- required.loadAppFunc- required.loadGrantFunc- required.ticket- optional ticket options used for parsing and issuance.hawk- optional Hawk configuration object. Defaults to the Hawk defaults.
callback- the method used to return the request result with signaturefunction(err, ticket)where:err- an error condition.ticket- a ticket response object.
Authenticates an application request and if valid, exchanges the provided rsvp with a ticket where:
req- the node HTTP server request object.payload- The HTTP request payload fully parsed into an object with the following keys:rsvp- the required rsvp string provided to the user to bring back to the application after granting authorization.
options- protocol configuration options where:encryptionPassword- required.loadAppFunc- required.loadGrantFunc- required.ticket- optional ticket options used for parsing and issuance.hawk- optional Hawk configuration object. Defaults to the Hawk defaults.
callback- the method used to return the request result with signaturefunction(err, ticket)where:err- an error condition.ticket- a ticket response object.
Provides direct access to the underlying Hawk module.
Scope manipulation utilities.
Validates a scope for proper structure (an array of unique strings) where:
scope- the array being validated.
Returns an Error is the scope failed validation, otherwise null for valid scope.
Checks whether a scope is a subset of another where:
scope- the superset.subset- the subset.
Returns true if the subset is fully contained with scope, otherwise `false.
Server implementation utilities.
Authenticates an incoming request using Hawk and performs additional Oz-specific validations where: Authenticates an application request and if valid, issues an application ticket where:
req- the node HTTP server request object.encryptionPassword- the ticket encryption password.options- protocol configuration options where:ticket- optional ticket options used for parsing and issuance.hawk- optional Hawk configuration object. Defaults to the Hawk defaults.
callback- the method used to return the request result with signaturefunction(err, credentials, artifacts)where:err- an error condition.credentials- the decoded ticket response object.artifacts- Hawk protocol artifacts.
Ticket issuance, parsing, encoding, and re-issuance utilities.
The following are the supported ticket parsing and issuance options passed to the corresponding ticket methods. Each endpoint utilizes a different subset of these options but it is safe to pass one common object to all (it will ignore unused options):
ttl- when generating a ticket, sets the ticket lifetime in milliseconds. Defaults to3600000(1 hour) for tickets and60000(1 minutes) for rsvps.delegate- iffalse, the ticket cannot be delegated regardless of the application permissions. Defaults totruewhich means use the application permissions to delegate.iron- overrides the default Iron configuration.keyBytes- the Hawk key length in bytes. Defaults to32.hmacAlgorithm- the Hawk HMAC algorithm. Defaults tosha256.ext- an object used to provide custom server data to be included in the ticket (this option will be ignored when passed to an endpoint method and theloadGrantFuncfunction returns anextvalue in the callback) where:public- an object which is included in the response underticket.extand in the encoded ticket asticket.ext.public.private- an object which is included only in the encoded ticket asticket.ext.private.
Issues a new application or user ticket where:
app- the application object the ticket is being issued to.grant- the grant object the ticket is being issued with if the ticket represents user access.nullif the ticket is an application-only ticket.encryptionPassword- the ticket encryption password.options- ticket generation options.callback- the callback method using signaturefunction(err, ticket)where:err- an error condition.ticket- a ticket response object.
Reissues a application or user ticket where:
parentTicket- the ticket object being reissued.grant- the grant object the ticket is being issued with if the ticket represents user access.nullif the ticket is an application-only ticket.encryptionPassword- the ticket encryption password.options- ticket generation options.callback- the callback method using signaturefunction(err, ticket)where:err- an error condition.ticket- a ticket response object.
Generates an rsvp string representing a user grant where:
app- the application object the ticket is being issued to.grant- the grant object the ticket is being issued with if the ticket represents user access.nullif the ticket is an application-only ticket.encryptionPassword- the ticket encryption password.options- ticket generation options.callback- the callback method using signaturefunction(err, rsvp)where:err- an error condition.rsvp- the rsvp string.
Adds the cryptographic properties to a ticket and prepares the response where:
ticket- an incomplete ticket object with the following:expappuserscopegrantdlg
encryptionPassword- the ticket encryption password.options- ticket generation options.callback- the callback method using signaturefunction(err, ticket)where:err- an error condition.ticket- the completed ticket response object.
Decodes a ticket identifier into a ticket response where:
id- the ticket id which contains the encoded ticket information.encryptionPassword- the ticket encryption password.options- ticket generation options.callback- the callback method using signaturefunction(err, ticket)where:err- an error condition.ticket- a ticket response object.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent