Generic Service Description

Resteasy Skeleton Key is SSO/OAuth capabilities for web apps and RESTful web services.  It will be a AS plugin, a standalone service, a cloud service, and a cloud SaaS.  The goal is to have an integrated distributed security solution for both

browser apps and RESTful web services.  The Skeleton Key service will be able to secure one ore more applications on different machines and different domain names.  It will provide a central location to login, logout, manage user logins, account registration, role mapping setup, etc.

Browser User-Agent Requirements

User Agents can visit any one of the applications on a network that are secured by the central Skeleton Key Service.  They will be redirected to the central Skeleton Key Service to perform authentication.  The User-Agent only has to login once.  Once they do, they are able to access any application on the network that is secured by Skeleton Key without having to re-enter their credentials.  A User-Agent should be able to logout in one place and be logged out of every application secured by the Skeleton Key Service.

Native-Client User-Agent Requirements

Native clients are code-based clients.  i.e. an iPad or iPhone App, Javascript running in a browser, or any native GUI application.  Really any app that performs authentication with the Skeleton Key Service via code instead of the browser.  Secure access is done by obtaining a bearer token from the Skeleton Key Service.  These clients send their credentials via a RESTFul HTTP request to the Skeleton Key Service and receive back a token.  With this token, the client can now access any HTTP-based service in the network of applications secured by Skeleton Key.

Server Application Requirements

Each server application will have to be registered with Skeleton Key and have their own specific set of credentials.  They will use these credentials to validate bearer tokens with the Skeleton Key Service, obtain security metadata from the Skeleton Key Service,  or to execute other management features of the Skeleton Key Service.  Secured application servers should not have to store any user data or any other security metadata like role mappings, etc.  A goal for the end product should be that the server application needs very little configuration data to bootstrap itself.  Ideally just the URI of the Skeleton Key Service, maybe a keystore to help set up a secure trusted SSL connection, the name of the security domain the application falls under, and finally the client id and credentials used to set up authenticated connections with the Skeleton Key Service.

On-Behalf-Of Clients Requirements

Third parties can be authorized to act on behalf of a user.  A better description of this is the OAuth 2 framework.  It describes pretty nicely the motivations for this.  Skeleton key will provide capabilities for authorizing these third parties via the OAuth 2 protocol framework.

Integration Requirements

A network of both browser-based apps and HTTP-based/RESTful web services should accessibe through one secured session.  Once a Browser User-Agent has logged in, Browser based applications should be able to access and delegate to remote RESTful services through a propagated bearer token.  For a Web app, tokens are propagated in-VM via the security context so that the web app can make remote invocations using that token.

Authentication and Authorization Metadata Requirements

Username and password are minimal requirements.  TOTP is something we want to support.  Client certificates should also be supported either as a sole authenticaiton mechanism or an additional one on top of username, password, etc.  For authorization, Skeleton Key will only provide support for user role mappings.  User role permission mappings should be configured per service/app within the security domain.  It will also provide scoping metadata for On-Behalf-Of Clients.  This scoping metadata defines which roles the third-party is allowed to request and act on behalf of the user.  Additional user and authorization metadata are the responsibility of external services and not in the scope of Skeleton Key.  However, Skeleton Key will integrate with these external services by binding hyperlinks to both the user and security domain (a.k.a. atom link relationships).

Password Recovery Requirements

If a user forgets their password, they can reset it by either sending an email or SMS message.  This email will have a callback URL to click.  This URL will ask a user defined question like "What was your mother's maiden name?" that the user has to answer.  If they answer correctly, then they can reset their password.  A security domain should be able to disable password recovery via configuration.

Bearer Token Management Requirements

Bearer tokens have the following requirements:

• Digitally signed either through a key pair or HMAC.  Key-pair is more secure, but for non-Java, non-JBoss apps HMAC might be easier
• Timestamped
• Not-Before and Not-After capabilities
• The digital signature of the token should be enough to verify the token.
• But, Bearer tokens should be verifiable at any time with the remote Skeleton Key service.
• Bearer tokens should contain minimal security metadata so that the application does not have to re-ping the central Skeleton Key service each and every time a new user comes in.  For example, role-mappings should be transmittable through the signed token.

Social Media Requirements

Skeleton Key Service should be able to optionaly act as a identity broker for users and applications that want to offer authentication via a Facebook, Google+, or other social media login.

Registration Requirement

Optionally, the Skeleton Key Service should have a browser-based mechanism for new users to register with and create an account.  The default roles mappings a new user would get should be configurable.

Identity Storage Requirements

Ideally the Picketlink IDM API should be used to obtain, store, and federate identity metadata.  Different levels of storing identity metadata should be configurable.  In some cases all identity metadata may be stored externally.  In these cases, there should not be an option for creating new users and role mappings and credentials.

Security Domain Management

There should be a management interface for each specific security domain.  A security domain manages access to a set of applications and services.  Here are some of the more fine-grain requirements.

• Mgmt UI to create accounts, domains, users, and role/permission mappings
• Mgmt UI can see what users logged in and what apps they have visited
• Mgmt UI can log out a user from all hosts in the domain
• UI for Token mgmt:  token expiration, not-before, not-after
• User-definable/configurable login screens for each domain.
• A REST interface to do all the things the management UI can do.

Deployment Options

Skeleton Key will offer multiple ways for users to consume. it.  It can be embeded within Wildfly/JBoss to secure a web-app locally.  It is packagable as a standalone service that manages a particular security domain.  It is deployable as a Cloud Service in which security domains can be created and managed by authorized users.  Finally it will be deployed on OpenShift as a Red Hat provided SaaS that anybody can use to create security domains.