Pre-Authentication (OAuth2) Tutorial · Description A brief description of the pre-authentication service. Pre-Authentication service This is a URL that points to the page where users

JOSSO 2.4

Pre-Authentication (OAuth2) Tutorial

JOSSO 2.4 : Pre-Authentication (OAuth2) Tutorial

iii

1. Introduction ................................................................................................................. 1

2. Prerequisites ................................................................................................................ 2

3. Defining Identity Appliance Elements .......................................................................... 3

3.1. Pre-Authentication element .................................................................................. 3

3.2. Identity Provider .................................................................................................. 4

4. Basic Client Application .............................................................................................. 5

4.1. SP Initiated SSO ................................................................................................ 5

4.1.1. Pre-Authenticated Token Request ............................................................. 5

4.1.2. Pre-Authenticated Token Response .......................................................... 5

4.2. IdP Initiated SSO ................................................................................................ 6

4.2.1. Unsolicited Pre-Authenticated Token Response ......................................... 6

4.3. Resolving the Security Token .............................................................................. 6

4.4. Authentication Service Examples ......................................................................... 6

4.4.1. OAuth2 Client Properties .......................................................................... 7

4.4.2. OAuth2 Resource Server Properties .......................................................... 7

4.5. OAuth 2 Client API ............................................................................................. 8

4.5.1. Method Summary: .................................................................................... 8

4.5.2. Method Detail: ......................................................................................... 8

4.6. OAuth 2 Resource Server API ........................................................................... 11

4.6.1. Method Summary: .................................................................................. 11

4.7. OAuth2 Access Token Object ............................................................................ 11

4.7.1. Method Summary: .................................................................................. 12

1

Chapter 1. IntroductionCustomers can rely on JOSSO’s security token service to act as authentication service, in case an

external application is required to gather user credentials on behalf of the Identity Provider. This

allows developers, to leverage their existing infrastructure as part of the product branding process,

or even when business specific rules need to be added while requesting user credentials.

JOSSO EE builds on the OAUTH2 standard to deliver security token issuance services.

JOSSO EE Pre-Authentication focuses on client developer simplicity while providing specific

authorization flows for web and desktop applications. The core concepts are simple: The end user

client application requests for a particular scope of access. With user approval (e.g. by sending

user credentials), the application will get a short-lived access token that can be used to establish

an SSO session.

JOSSO EE Token-based authentication defines four roles :

• Resource owner: An entity capable of granting access to a protected resource (e.g. end-user).

• Client: An application making authentication requests on behalf of the resource owner and with

its authorization, in this case, the client will be an external web application.

• The Identity server issuing access tokens to the client after successfully authenticating the

resource owner and obtaining authorization.

In this tutorial, we will start with an existing SSO setup using basic authentication (username/

password), and we will modify the authentication mechanism for the Identity Provider, enabling

pre-authentication.

Let’s take a look at the entire authentication flow, this example assumes a JOSSO Agent based

partner application as Service Provider, but the IdP and Client parts apply to any provider type

(External SAML2, etc).

2

Chapter 2. PrerequisitesBefore starting, make sure that the following prerequisites are meet.

• JOSSO 2.4.1+ instance: JOSSO 2 Server hosting an OAuth2 capable IdP.

• Working SSO environment: an already working Identity Appliance using built-in basic

authentication.

• Client application: Web application requesting access tokens based on user credentials.

This is our starting Identity Appliance, it contains two service providers: a Tomcat JEE application,

and cloud service (Google Apps), both trusting our Identity Provider.

3

Chapter 3. Defining Identity

Appliance ElementsThe first step is to modify our SSO deployment, enabling the necessary functions in the IdP that will

support pre-authentication. First we well ad a pre-authentication element to the model, connecting

it to the IdP using an Identity Verification connection. Then we well update the Authentication

section of the IdP, by sorting the available Authentication mechanisms. Finally we will configure

the OAuth 2.0 section; this requires enabling the protocol for the IdP, and adding a new OAuth

client entry to the trusted clients list.

3.1. Pre-Authentication element

Let’s start defining the new Pre-Authentication mechanism. First we need to select the proper

element from the Authentication drawer on the right. When we place it on the model, the creation

pop-up will display, requesting the following properties:

Property Description

Name The mechanism name, set to pre-authn by

default. Normally this value does not need to

be modified.

Description A brief description of the pre-authentication

service.

Pre-Authentication service This is a URL that points to the page

where users will be redirected upon login.

The necessary OAuth2 information will

be appended to the value, as request

parameters (i.e relay_state).

Remember Me Enabled in case the IdP should enable

remember me support

The key property here is the Pre-Authentication service URL, the value refers to the OAuth 2

Client endpoint that will be handling pre-authentication requests. We will take a closer look at the

Client later.

Upated Identity Appliance

Defining Identity

Appliance Elements

4

3.2. Identity Provider

Now that the new authentication mechanism has been added, we can start making the necessary

changes to the IdP definition. The added element will appear in the list of authentication

mechanism configured for the IdP, part of the Authentication section. We need to sort these

elements properly; JOSSO will attempt to authenticate users by selecting a mechanism them from

top to bottom, so if we want pre-authn to be used insted of the built-in basic authentication, we must

drag it to the top of the list. We still need basic authentication enabled, because when the We can’t

disable basic authentication, because when the Client application requests an access token using

user credentials, JOSSO will use it to validate them. Note thate the basic, built-in authentication,

can be replaced by a directory based authentication in case Active Directory is being used.

The last change requires enabling OAuth 2.0 support on the IdP.


Enabled Enables OAuth 2.0 support. When enabled,

the appliance build process will generate and

configure the necessary artifacts

Enabled Flows Selected OAuth 2.0 flows.

Enabled bindings Supported protocol bindings, SOAP is

actually a JOSSO extension of OAuth2, to

support the pre-authentication use-case.

Server Key Used to encrypt the Access Token.

Clients Configuration JSON Script defining an array of trusted client

definitions, represented by the client id and

secret.

5

Chapter 4. Basic Client ApplicationThe Client Application, also referred as Pre-Authentication service, is a web application that

collects user credentials and is able exchange OAuth 2 messages with the IdP as part of the

authentication process. There are two main scenarios that should be handle by the client:

• SP Initiated SSO: In this case, the client will process a pre-authentication token request issued

by the IdP due to an authentication request recevied from a Service Provider. This is the case

when a user access an application, and it requests user authentication from JOSSO.

• IdP Initiated SSO: In this case, the user will be directly authenticated by the IdP, and then

forwarded to a Service Provider without an express authentication request. This normally occur

when users access the authentication service directly (login page), and after completing the

process, the user is redirected to a default resource (i.e. main portal, etc).

JOSSO provides an API that will help you handle the message exchange, and request access

tokens. Currently .Net and Java clients are available.

4.1. SP Initiated SSO

In this mode, JOSSO will issue a pre-authentication token request to the client, the request is in

the form of a URL, where request parameters represent different attributes:

4.1.1. Pre-Authenticated Token Request


request_id Request unique identifier

relay_state IdP state value, it must be sent as part of the response. JOSSO

will use it to validate the received message

issuer IdP alias, base64 encoded

authn_ctx (*) Authentication Context class requested (OAuth 2)

target SP alias that requested the authentication, base 64 encoded

4.1.2. Pre-Authenticated Token Response


response_id Unique response identifier

atricore_security_token OAuth 2 access token, obtained using the provided OAuth2 API

relay_state This value must match the one provided in the original request

scope This value must be set to preauthn-token

Basic Client Application

6


replay This must be set to the original request_id

remember_me Boolean value requesting "Remember Me" option for this login.

Optinal, if not present false is assumed.

4.2. IdP Initiated SSO

Sometimes we want to start the SSO process from the IdP (or the authentication service), and

redirect the user to a specific application once authenticated. This is known as IdP initiated SSO.

In this case, the client will obtain a security token, and will issue a response that includes the

targeted SP (application).

4.2.1. Unsolicited Pre-Authenticated Token Response


response_id Unique response identifier (optional)

atricore_security_token OAuth 2 access token, obtained using the provided OAuth2 API

scope This value must be set to preauthn-token

atricore_sp_alias SP Alias, base64 encoded where user will be redirected

remember_me Boolean value requesting "Remember Me" option for this login.

Optinal, if not present false is assumed.

4.3. Resolving the Security Token

It is possible to resolve the received token, this means that the client will be able to obtain

information about the current user. This is normally the role of the resource server, therefore

additional components need to be included in our application. Specifically the OAuth2 Commons

and OAuth2 Resource Server libraries must be added. (There are Java and .Net versions of this

components).

4.4. Authentication Service Examples

JOSSO Provides two examples that will help you build your own authentication service:

• Java Example : https://github.com/atricore/atricore-idbus/tree/1.4.2/examples/oauth2-

preauthn-app

• .Net (C#) Example : https://github.com/atricore/atricore-idbus/tree/1.4.2/examples/oauth2-

preauthn-app

The key element in the listed examples is use of the OAuth2Client component. It allows developers

to easily handle the message exchange, without having to deal with the details. Let’s take a look

at the configuration properties:

https://github.com/atricore/atricore-idbus/tree/1.4.2/examples/oauth2-preauthn-app





7

4.4.1. OAuth2 Client Properties


clientId OAuth2 client identifier, as defined in the OAuth2

section of the trusted IdP

clientSecret OAuth2 shared secret,<add key="oauth2SharedSecret"

value="changeme"/> as defined in the OAuth2 section

of the trusted IdP

authnEndpoint /

authorizationServerEndpoint

OAuth 2 service endpoint (SOAP), where tokens will

be requested. Format: <protocol>://<sso-server>:<sso-

port>/IDBUS/<appliance-id>/<idp-id>/OAUTH2/

TOKEN/SOAP, all in uppercase.

spAlias / serviceProviderAlias Service Provider Alias (SAML 2 alias), base64

encoded used as default SP, only required when

using IdP initiated SSO and no SP is specified by the

Authentication Service

idpInitPreAuthn The IDP initiated SSO authentication URL (optinal).

Format: <protocol>://<sso-server>:<sso-port>/IDBUS/

<appliance-id>/<idp-id>/SAML2/SSO/IDP_INITIATE, all

in uppercase.

idpPreAuthnResponse . Format <procotol>://<sso-server>:<sso-port>/IDBUS/

<appliance-id>/<idp-id>/CC/OAUTH2/PRE-AUTHN/

REST, all in uppercase.

4.4.2. OAuth2 Resource Server Properties


oauth2SharedSecret/

org.atricore.idbus.capabilities.oauth2.key

OAuth2 shared secret, matching the shared secret

configured in the IdP

Java OAuth2Client configuration example, this is a Java properties file.

oauth2.clientId=acme

oauth2.clientSecret=acme123

oauth2.authnEndpoint=https://sso.mycompany.com/IDBUS/TEST1/IDP1/OAUTH2/

TOKEN/SOAP

oauth2.spAlias=https://sso.mycompany.com/IDBUS/TEST1/SP1/SAML2/MD

oauth2.idpInitPreAuthn=https://sso.mycompany.com/IDBUS/TEST1/IDP1/SAML2/SSO/

IDP_INITIATE

oauth2.idpPreAuthnResponse=https://sso.mycompany.com/IDBUS/TEST1/IDP1/CC/

OAUTH2/PRE-AUTHN/REST

Net OAuth2Client configuration example, this is a .Net Application configuration file.


8

<appSettings>







<add key="clientId" value="acme"/>

<add key="clientSecret" value="acme123"/>

<add key="authorizationServerEndpoint" value="https://sso.mycompany.com/

IDBUS/TEST1/IDP1/OAUTH2/TOKEN/SOAP"/>

<add key="serviceProviderAlias" value="https://sso.mycompany.com/IDBUS/

TEST1/SP1/SAML2/MD"/>

<add key="idpInitPreAuthn" value="https://sso.mycompany.com/IDBUS/TEST1/

IDP1/SAML2/SSO/IDP_INITIATE"/>

<add key="idpPreAuthnResponse" value="https://sso.mycompany.com/IDBUS/

TEST1/IDP1/CC/OAUTH2/PRE-AUTHN/REST"/>







<add key="oauth2SharedSecret" value="changeme"/>

</appSettings>

4.5. OAuth 2 Client API

As stated before, the OAuth client API can be used to process the received request, and to issue

the proper responses.

4.5.1. Method Summary:

Modifier and Type Method and Description

void init()

String buildIdPPreAuthnResponseUrl(String relayState, String usr, String pwd)

String buildIdPPreAuthnResponseUrl(String relayState, String accessToken)

String buildIdPInitPreAuthnUrl(String spAlias, String username, String

password)

String buildIdPInitPreAuthnUrlForDefaultSp(String username, String

password)

String buildIdPInitPreAuthnUrlForToken(String accessToken, String spAlias)

String requestToken(String username, String password)

4.5.2. Method Detail:

4.5.2.1. init

Initialises the client, by reading the configuration options. It only needs to be invoked once, while

instantiating the client. In the Java version, it will try to resolve the oauth2.properties file. In .Net,

it will read configuration properties from the application environment.


9

Parameters

N/A

Returns

N/A

4.5.2.2. buildIdPPreAuthnResponseUrl

Create an pre-authentication token response, in the form of a URL. This can be used by the pre-

authentication service to redirect the user back to the IdP.

Parameters

• String relayState, the relay state value received as part of the pre-authentication request.

• String username, the credential provided by the user, and collected by the pre-authentication

service application.

• String password, the credential provided by the user, and collected by the pre-authentication


Returns

• String: the pre-authentication response in the form of a URL.

4.5.2.3. buildIdPInitPreAuthnUrl

Create an unsolicited pre-authentication token response, in the form of a URL. This can be used

when the pre-authentication service needs to start the SSO process without a previous request.

The target application (SP) must be specified.

Parameters

• String spAlias, the SAML 2 SP alias, base64 encoded.





Returns



10

4.5.2.4. buildIdPPreAuthnResponseUrl

Create an pre-authentication token response, in the form of a URL. This can be used by the pre-

authentication service to redirect the user back to the IdP.

Parameters

• String relayState, the relay state value received as part of the pre-authentication request.

• String accessToken, the OAuth2 access token normally obtained by using the requestToken

method

Returns


4.5.2.5. buildIdPInitPreAuthnUrlForDefaultSp



The target application (SP) will be take from the client configuration properties

Parameters





Returns


4.5.2.6. buildIdPInitPreAuthnUrlForToken



The target application (SP) will be take from the client configuration properties

Parameters

• String accessToken, the OAuth2 access token, previously obtained using the requestToken

method.

Returns


11


4.5.2.7. requestToken

Request a new security token for the provided credentials, it is up to the client to create the proper

response URL using the received token.

Parameters





Returns

• String: the security token, encrypted and digitally signed.

4.6. OAuth 2 Resource Server API

The key component of this API is the AccessTokenResolver, it allows Resource Servers to

resolve an access token, and get a representation for the user information. The currently support

implementation is the SecureAccessTokenResolver, that uses AES and HMAC to decrypt and

verify tokens issued by JOSSO IdPs. Component configuration and instantiation in depends on

the Resource Server platform (.Net or Java), you can refer to the provided examples for details

on how to initialize the resolver.


Modifier and Type Method and Description

OAuth2AccessToken resolveToken(String relayState, String usr, String pwd)

4.6.1.1. resolveToken

Resolves an access token string representation into an OAuth2AccessToken instance.

Parameters * String, accessToken*, the OAuth2 access token, issued by a JOSSO IdP.

Returns an OAuth2AccessToken instance.

4.7. OAuth2 Access Token Object

Token object instance, provides information about user identifier (username), user roles and

attributes or properties.


12


*Modifier and Type

*

Method (Java/.Net) and Description

String getUserId/UserId

String getAttribute(String attributeName)

Boolean isUserInRole(String roleName)

List<OAuth2Claim> getClaims/Claims

Documents

Pre-Authentication (OAuth2) Tutorial · Description A brief description of the pre-authentication service. Pre-Authentication service This is a URL that points to the page where users