Category Archives: OpenAM

Step-Up Authentication Scenarios with AD FS 2.0 Part I

This post refers to additional logon schemes that can be supported in AD FS by forcing users to re-authenticate or step-up/step-down authentication to federated web applications. It was prompted by a  recent request from a customer :

“We wish to connect a SAML 2.0 Service Provider (SP) to AD FS. For security reasons,  we require our internal users to logon (again) when connecting to this web application. All users connecting through the AD FS proxy should be prohibited access.”

Whether we choose to call this process re-authentication or step-up authentication really depends on the access case.  To meet the requirement, we’ll be breaking single sign-on (SSO) when accessing the web application above by sending parameterised requests from the web application to AD FS, specifying how to handle authentication uniquely for this app.

Some folks may have pre-conceived ideas about what constitutes step-up, perhaps because it is often associated with multi-factor authentication. While the two do complement one another nicely, step-up is not necessarily multi-factor.  Rather, use of step-up as an access mechanism, is governed by the strength of authentication we wish to accrue to access, at a level commensurate with requirements for protecting that resource. We can use weaker (single factor) authentication where this is deemed sufficient or appropriate.  As an example, a customer may employ two-factor authentication on the outside/edge for all users and then elect to use the AD password, as an additional step-up mechanism for corporate users only to gain access to internal resources.  In authentication strength terms, this is step-down authentication, but in functional terms, it’s designed as a step-up method.

I make the above point, because in the examples described here, we have users logging onto their workstations either using weak (username/password) or strong (two-factor) authenticating against other federated web applications with these credentials.  In each case, we plan on forcing users to logon again when they access this particular SAML 2.0 web application to “step-up” security.

This is an internal only access scenario for the enterprise, meaning that users connecting via the AD FS Proxy should be denied access. Since AD FS Rollup 1, we’ve been able to specify Issuance Authorization Rule on the relying party (SAML 2.0 SP) pipeline that allows requests sourced from the AD FS Proxy to be identified and acted on via the claim description: http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy

Accordingly, we’ll create a deny Issuance Authorization Rule on our SAML web application so that users connecting through the proxy will be blocked.

exists([Type == “http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy”]) => issue(Type = “http://schemas.microsoft.com/authorization/claims/deny”, Value = “true”);

Sample Scenario

In a default AD FS farm setup, a domain-joined Windows machine internal user connects to the AD FS farm and authenticates via the Integrated Windows Authentication (IWA) handler using Kerberos/NTLM.  To alter this behaviour, for a given application, and force the user to re-authenticate, we must ignore the existing session cookie.

With WS-Federation, we can do this at AD FS, via a smart link, by specifying the wauth parameter:

https://sts.mydomain.com/adfs/ls/?wa=wsignin1.0&wtrealm=https://rp.mydomain.com &wauth=urn:oasis:names:tc:SAML:1.0:am:password

For a relying party using the WS-Federation Passive Requester Profile (WS-PRP) we can also specify the request in the query string or within application code also via wauth.

This is a SAML 2.0-based use case though. As a backgrounder, I suggest reading about SAML Authentication Context Classes and Strengths with AD FS. Within the SAML 2.0 protocol, SAML service provider (SP) can emits certain values in the SAML request that ensures that the required authentication method from the SP is honoured by AD FS. From an SAML 2.0 protocol standpoint, this may be accomplished by:

  1. Setting an Authentication Context Class Reference (AuthnContextClassRef) in the requested authentication context from the Service Provider;
  2. Specifying the use of Force Authentication (ForceAuthn) in the request set to a value of true;
  3. Use of a Comparison rule that is set to exact to expressly set the authentication method. Other settings are also possible (which AD FS supports) but are not covered in this post.

Let’s look at the farm-connected conventions mentioned above in a bit more detail.

Authentication Context Class Reference

In Windows SSO logon scenarios, the AD FS integrated handler uses the SAML  AuthnContextClassRef of urn:federation:authentication:windows. On our SAML 2.0 web application, we’ll request a authentication context class reference of urn:oasis:names:tc:SAML:2.0:ac:classes:Password, so that the forms handler (in AD FS) is targeted as the desired authentication handler.

Force Authentication

The specification of ForceAuthn=true in the initial SAML request from the service provider specifies that the Identity Provider (IdP) should force re-authentication of the user, even if they possess a valid session with AD FS.

Comparison Rule

The SAML 2.0 protocol supports the use of a comparison rule to determine the level of precision to be accorded to the authentication request. If none is specified, AD FS will assume that the attribute is set to exact, meaning that authentication should conform exactly to the AuthnContextClassRef request and is passed to the appropriate handler.

Configuring Service Providers

I’ve used two examples here:

  • OpenAM
  • SimpleSAMLphp

I also planned on including Shibboleth, but hosed my configuration in the process, by reverting the wrong Snapshot of my VM during testing.. *cough*… sorry about that Smile 

OpenAM

Using OpenAM as a SAML SP example, we’ll invoke SP-initiated sign-on through the spSSOInit.jsp page.  In the query string we’re specifying the authentication context and the desired force authentication.

https://myapp.mydomain.com/openam/saml2/jsp/spSSOInit.jspmetaAlias=/acs/sp&realm=acs &ForceAuthn=true&AuthnContextClassRef=urn:oasis:names:tc:SAML:2.0:ac:classes:Password &idpEntityID= http://adfs.mydomain.com/adfs/services/trust&RelayState=https%3A%2F%2Fmyapp.mydomain.com%2Fopenam%2Fconsole

Note: The above syntax is valid but watch out for white spaces in the example above, not to mention your own domain name.  I’ve added spaces to make the text more legible.

AD FS will parse the request based on the emboldened items in the query string and ask the user to re-authenticate via forms sign-in.

SimpleSAMLphp

In SimpleSAMLphp, we can set the necessary settings in the configuration file authsources.php, specifying the authentication context and force authentication requirement.

‘ForceAuthn’ => TRUE,
‘AuthnContextClassRef’ => ‘urn:oasis:names:tc:SAML:2.0:ac:classes:Password’,

Authentication Options

How we choose to implement our step-up/re-authentication component depends on the question of sufficiency and what is an acceptable method to choose.  For this exercise, this could mean:

  1. re-using the Windows logon identity (re-authenticate);
  2. using an alternate identity from within the same AD forest (step-up);
  3. using an alternate identity residing in a connected forest (step-up);
  4. using an alternate authentication service; a third-party application that provides stronger forms of authentication

Option 1 – Re-Authentication

The  simplest option  sees the the user replaying their AD credentials, logging on again via the AD FS form, before gaining access to the web application. This is clearly not step-up and doesn’t afford any significant additional protection, , but may fulfil compliance/auditing requirements for access.

Advantages Disadvantages
Simple (uses same identity) Re-authentication not step-up authentication (same password policy)
Protects against inadvertent access to the application if the user is already logged on (e.g. where user fails to lock OS)

Security gain is nominal. Requires claims authorization rules on the relying party to differentiate between valid/invalid users.

Option 2 – Step-Up Same Forest (username/password)

Option 2 uses another set of credentials held within the same AD FS forest. Access to the SaaS application is limited to those users using these credentials (i.e. their “step-up” identity) and an authorization rule to supplement this.

image

 

Advantages Disadvantages
Authentication is stepped using another identity besides the corporate logon More complex. Requires additional identity to represent users (user management)
Supports use of stronger password policies on the second identity

Security gain is moderate.  Same factor (username / password) for step-up identity

  Less user friendly (extra identity)
  Shared authentication sources between identities (no isolation)

Option 3 – Step-Up Connected Forest (username/password)

A more complex rendition of this using multiple forests with a single AD FS instance (Option 3):image

In the above setup we have an account forest for our corporate users and a resource forest, where the AD FS server lives (with the AD FS application pool account running in the account forest). A one way forest trust between the two exists. In this option, the step-up identities reside in the resource forest.

Advantages Disadvantages
Authentication is stepped using another identity besides the current logon

More complex. Requires additional identity / shadow account represented in the  remote forest  (user management)

Supports use of stronger password policies on the alternate identity

Security gain is moderate. Same factor (username/ password)  for step-up identity

Shadow account can use same sAMAccountName in remote forest Less user friendly (extra identity)
Greater isolation / independence of action from account forest (supports selective authentication) More complex to manage

For Options 2 and 3, we can also provide further refinement by using AD fine-grained password policies to implement a stronger password policy / account lockout policy applicable to our web application, that exceeds the ordinary password policy levels used for for corporate AD users.

In all above cases, we should consider further restraining access by passing custom claims on the relying party, to assist in determining whether the user in question should have access.

From an AD FS standpoint, there are no configuration changes required in the cases described thus far.  You may note, however, that I’ve not yet mentioned IdP-Initiated Sign-On methods. SHAME! Well, there’s a couple of reasons for this, by which I’ll conveniently recuse myself Smile with tongue out 

  1. Firstly, there a nice solution posted on CodePlex, that works similar to the actions described in this post, albeit by customizing the AD FS sign-in pages instead. It allows assigning the use of forms logon logic to relying parties and also covers IdP-Initiated Sign-On and WS-Federation.    Relying parties registered to use the forms logon are registered in AD FS web.config file, thereby bound to the forms handler.
  2. Also, some customers may be unwilling to modify their default AD FS setup because of a fear that it will throw them outside the realms of Microsoft support. However, if you do wish to support IdP-Initiated sign-on scenarios using the methods above (AuthnContextClassRef and ForceAuthn),  then I’m afraid you don’t have much choice as customization of the  code-behind page for  idpinitiatedsignon.aspx.cs is required. Without these changes, sign-on, either via  logintoRP or relaystate  query parameters, will fail as the desired authentication context (AuthnContextClassRef) has not been set and is not passed by the IdP to the service provider. I used the following MSDN article as a reference to customize the  idpinitiatedsignon.aspx.cs and then tested this using logintoRP parameter, with the query string example below.

https://adfs.mydomain.com/adfs/ls/IdpInitiatedSignon.aspx?logintorp=https:/app.mydomain.com/web1/&RequestedAuthenticationContext=urn:oasis: names:tc:SAML:2.0:ac:classes:Password&ForceAuthentication=true

In Part II, we’ll look at step-up options with stronger / multi-factor authentication methods (aka Option 4). See ya!

A little more OpenAM……10.0

OpenAM 10 Early Release is now available for download and there’s lots of changes and new access capability/features in there:

  • OpenIG – ForgeRock Identity Gateway. A reverse proxy with credential replay to support OpenAM for non-federated web applications.
  • New SAML 2.0 IdP Adapter plug-in that allows additional processing to be performed before releasing the assertion or when some form of user interaction may be required.
  • OAuth 2.0 Client Authentication Module
  • OpenAM .NET Fedlets with support for encrypted assertions
  • Support for adaptive risk authentication
  • Support for multiple RADIUS servers in RADIUS authentication module
  • Distributed Authentication Service (DAS) HTTP Header mapping when forwarding requests
  • Support for LDAP servers that support Behara IETF draft Password Policy for LDAP Directories, e.g. OpenDJ, OpenLDAP
  • Active Directory password expiration response processing (correct)
  • Windows Desktop SSO, kerberos and user profile improvements

Completely selfish of me, I’ve hand-picked the stuff from the Release Notes that I thought particularly interesting or was bugging me in earlier releases Smile

Forgerock OpenAM 9.5.3 and AD FS 2.0 Integration – Part 3

In the final part of this configuration, we’ll look at setting up both AD FS and OpenAM for federation.

Before we start, let’s quickly recap on the access scenario.  OpenAM is an identity provider in another organization, with whom we are performing identity federation with. 

image

We intend to provide users  in Organization A with access to web resources in Organization B.  This is accomplished by setting up a federation trust via the local AD FS 2.0 instance in Organization B. Communication is across an untrusted network; consequently, all traffic between parties is encrypted using HTTPS.

In  Part 2, we created the identity provider on the OpenAM side and registered the remote AD FS SAML 2.0 service provider. A few tasks still remain though:

  • Finalize the OpenAM Identity Provider (IdP) Configuration
  • Configure the Remote AD FS 2.0 Service Provider (SP) in OpenAM
  • Configure the Identity (Claims) Provider in AD FS 2.0
  • Create test users in OpenAM
  • Configure a Windows Identity Foundation (WIF) test application
  • Configure AD FS 2.0 claims

Finalize the OpenAM Identity Provider (IdP) Configuration

There are a couple of changes that we need to make on the OpenAM IDP side. The IDP attribute mapper is used to specify which user attributes will be included in an assertion. The default attribute mapper (com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper) retrieves attribute mappings from the (user) data store and sets that value as the attribute value of the specified SAMLV2 attribute.

Assertion Content

On this tab of the IdP configuration, we’re going to specifiy the NameID format that the Identity Provider will use and also the value mappings to map the Name ID to.  A number of NameID formats are supported by OpenAM, according to the SAML 2.0 protocol:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
urn:oasis:names:tc:SAML:2.0:nameid-format:entity

In this example, we’ve set the Name ID format on the IdP to accept both a NameID format of Transient or Unspecified. 

image

We want to create a mapping with the selected format to an attribute from the user’s profile. In our case, the defined Name ID format is used in the protocol, resulting in the profile attribute value being used as the NameID value for the user. In the example below we map the transient format to the user common name (cn) attribute and unspecified to the user ID (uid) attribute.

image

Note that the default NameID convention that AD FS will follow/submit as a SAML 2.0 Service Provider (unless told otherwise) is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified . For more information, I’d suggest reading a great article from Adam Conkle on Technet :

http://social.technet.microsoft.com/wiki/contents/articles/4038.aspx

Assertion Processing

image

In the Assertion Processing section of the IDP we map the configuration used by the attribute mapper. Using the convention of SAML v2-attribute=user-attribute convention, we map, in the above example, the user store userattribute of uid to the SAML attribute uid, the Common Name of the object and the mail address.

 

Configure the Remote AD FS 2.0 Service Provider (SP) in OpenAM

Under Entity Providers in OpenAM we need to configure settings for the SAML 2.0 Service Provider, AD FS 2.0.

Assertion Content

Under the Assertions Content tab, check that that the Assertions are Signed.

image

We’ll also inform the SAML 2.0 Service Provider of the NameID formats supported/expected. An identifier is used so that both parties can agree on third-party authentication of a user, using identifiers that are meaningful to both. Here we configure that the expected NameID format and the content presented by AD FS 2.0 is an identifier with transient semantics or one of unspecified.

image

We’ll set this also on the AD FS 2.0 claims provider shortly.

Assertion Processing

The assertion processing tab allows us to map attributes to submit to the relying party/Service Provider.  This provides us with an opportunity to map through our custom claims descriptions as SAML attributes to the corresponding attributes in the OpenAM user directory.

image

You may recall that we created these custom claims descriptions earlier in Part 2 and we can now use these descriptors to map against their OpenAM LDAP counterparts.

Configure the Identity (Claims) Provider in AD FS 2.0

In AD FS 2.0 we need to register our OpenAM SAML 2.0 Identity Provider. Create a Claims Provider and point AD FS to the online OpenAM metadata address. In a lab/testing environment, using online metadata publishing is fine. Across untrusted networks, and in production environments, organizations may be reluctant to publish metadata online, in which case file exchange is an option.

image

We’re not using realms within OpenAM, so the default URL for the IdP under the root realm is used. Using the naming example of idp.mydomain.com  from our previous posts, the IdP service endpoint, therefore, would be:

 https://idp.mydomain.com/openam/saml2/jsp/exportmetadata.jsp

image

Click past the skipped federation metadata warning.

image

Give your Claims Provider a name. ***

image

Validate that the selected URL and federation partner information is correct.

image

You can add the claims now (detailed below) for the IdP or uncheck the Open Edit Claim Rules dialog as I’ve done here, adding the claims later. I’ve chosen here to adjust the claims provider properties first before setting up the claims rules, but it’s ultimately down to personal preference…

image

On the IdP properties, click on the Advanced tab and change the hashing algorithm from SHA-256 to SHA-1 and click on Apply / OK when done.

*** Note that this will be the name used on the Home Realm Discovery page and the user will need to select between the local AD FS 2.0 realm or the OpenAM IdP realm (assuming that local AD FS authentication hasn’t been disabled (a la https://blog.auth360.net/2011/02/20/disable-local-authentication-in-ad-fs-2-0/)

Configure a Windows Identity Foundation (WIF) test application

This is a well documented process by Microsoft, so I’m not going to spend much time on this section Smile 

To get your WIF application running I’d suggest reading this article

http://technet.microsoft.com/en-us/library/adfs2-federation-wif-application-step-by-step-guide(v=ws.10).aspx

Alternatively, you can use a Sharepoint 2010 Claims web part (if you happen to have Sharepoint floating around)… For the remainder of this document, I’m assuming that you’ve gone the WIF route and the assumption therefore is that this will be the relying party.

Here’s a screenshot of the FEDUTIL tool and setting up the Application URI.

Hint: Look at using the ClaimsAwareWebApplicationWithManagedSTS

image

Once you’ve configured your Claims aware web application via FEDUTIL, it’s time to configure the Relying Party (RP) on the AD FS 2.0 side. Now this could be another SAML 2.0 Service Provider, but in the .NET world (at the moment) this is not released yet (CTP). So, in the above example, we’re using a relying party that has a WS-Federation Passive endpoint of https://contoso.auth360.net/sts with metadata at: https://contoso.auth360.net/sts/FederationMetadata/2007-06/FederationMetadata.xml

Create Test User in OpenAM

Let’’s assume that we’re using the built-in datastore as the default authentication store for users.

image

If we go into Access Control, select the Top Level Realm and then click on Authentication, we’ll see that ldapservice (Datastore) is the organizational authentication scheme for our users (note there is a separate authentication scheme for realm admins) , so we’ll need to create a user with a password. From the Top Level Realm, select Access Control | Top Level Realm | Subjects | New

image

Fill out the mandatory fields (denoted by an asterisk) for the user. The ID field is the logon ID used for subsequent logon.

image

One item to check is the User Profile in the Authentication tab of the Top Level Realm. Click on All Core Settings and check that the User Profile is set to Required. I notice to my cost, that if this is set to Dynamic or Ignored then OpenAM will not pass any user SAML attributes to the AD FS service provider apart from NameID. I’ll be honest… I don’t know whether this is my testing, a bug or is by design, but it certainly proved to be a quirky stumbing block in my test setup Smile

 

Configure AD FS 2.0 Claims

Back in AD FS world, we’ll need to setup claims on both the Claims Provider (OpenAM IdP) and Relying Party (WIF) side of things.

Claims Provider

image

In Claims Provider Trusts, right click on the OpenAM IdP and select Edit Claim Rules.

We’re going to create the following rules as seen in the screenshot below.

image

If you’ve followed the previous articles, then you should have two custom claims descriptions already for UID and Mail, so it should be relatively easy to creat the mappings thru the GUI using the above claims or below using custom rules based on:

  • NameID set to Transient (which is the Common Name attribute from OpenAM)
  • Pass thru Custom Claims Description for AM UID (which is the uid attribute from OpenAM)
  • Pass thru Custom Claims Description for AM UID (which is the mail attribute)

The transient rule looks like this:

image

[Pass thru Incoming Claim Type of Name ID and Incoming Name Format Transient Identifier – Pass All Claims Values]

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] == "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"]
=> issue(claim = c);

[Pass thru Incoming Custom Claim for UID – Pass All Claim Values]

c:[Type == "http://schemas.auth360.net/2012/01/requestcontext/claims/x-am-uid"]
=> issue(claim = c);

[Pass thru Incoming Custom Claim for Mail – Pass All Claim Value]

c:[Type == "http://schemas.auth360.net/2012/01/requestcontext/claims/x-am-mail"]
=> issue(claim = c);

Relying Party

In the Relying Party Trust section within AD FS, we also need to create some pass thru rules on our WIF web application. We can use the same rules defined above. Follow the same process, albeit this time right-clicking on the relying party and editing the claims rules on the RP. I’ve also added a transform rule in testing to transform the x-am-mail claim to UPN (see the screenshot below). It’s not required, but is merely used to demonstrate how incoming values can be also be transformed/passed to other attributes.

[Transform Custom Claim for Mail – UPN]

c:[Type == "http://schemas.auth360.net/2012/01/requestcontext/claims/x-am-mail"]
=> issue(Type = "
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType);

Summary

With all the parts coming together, here is the abridged version of the logon process, starting at the relying party.

  1. User in Organization A accesses https://contoso.auth360.net/sts (Relying Party) in Organization B.
  2. User does not have a valid authentication cookie and so is redirected to Organization A https://sts.mydomain.com/adfs/ls (FP-STS) . for logon
  3. AD FS performs Home Realm Discovery
  4. User selects their Organization A home realm (OpenAM IdP) for logon
  5. User is redirected to Organization A https://idp.mydomain.com/openam/SSORedirect/metaAlias/idp?SAMLRequest
  6. User logs on to OpenAM realm with local user account and is authenticated
  7. User is redirected back to AD FS (FP-STS) for further processing
    • AD FS processes (Claims) Acceptance Transform Rules on Claims Provider
    • AD FS processes (Claims) Acceptance Transform Rules on Relying Party
  8. User is redirected to relying party web application https://contoso.auth360.net/sts.

I’m simplifying the logon process somewhat to give a more concise view of events, not to mention saving me typing…  It’s important to note that since this is a passive web federation scenario, the browser and user are effectively bounced around from RP to FP-STS/SP to IdP and back during the logon process.

In the claims-aware web application, the resultant claims should be now visible.

image

That’s it on the configuration side of things! If you come unstuck, just post comments and I’ll try and get back to you ASAP. I hope this helps those who are looking at integrating OpenAM with AD FS. Meanwhile, as ever, this is all done in the hygienic and wonderful user free environment of a test lab, so don’t go all production grade on me without beating this first with the testing stick……

Forgerock OpenAM 9.5.3 and AD FS 2.0 Integration – Part 2

It’s been a couple of months since Part 1, so time to put pen to paper. I’ll post Part 3 up in the next few days. Sorry for those who’ve had to wait…

In the previous OpenAM/AD FS  post we covered the installation of OpenAM . In this post we’ll concentrate on preparing the platforms for identity federation. One thing I won’t be doing is covering the actual installation of AD FS 2.0. That’s well documented elsewhere. I’ll assume that you have a working AD FS 2.0 configuration.

We’ll begin on the AD FS 2.0 side by creating two custom claims descriptions. If you read the previous post concerning AD FS 2.0 Rollup 1: Client Access Policy Support for O365, then you may recognize this process.  From the AD FS 2.0 MMC snapin and service panel, I’ve create two custom claims descriptions:

image
image

It’s important to stress that the URLs are not real ones. They are there for reference and administrative purposes and:

  • they are to aid managing our rulesets and are used in the federation metadata exchange between OpenAM and AD FS 2.0.

  • using short attribute names for claims type descriptions, e.g. mail, uid etc.,  while possible, can causes headaches, particular with multiple claims providers, as we’re dealing with common attributes / descriptions. A provider-specific namespace helps avoid this confusion;

  • we want to create a unique association between the entities concerned: OpenAM and AD FS 2.0…

We’ll reference these claim descriptions on the OpenAM side later in the setup process. We create them now so that when we register the remote service provider in OpenAM, the relevant metadata is there.

Let’s return to OpenAM …… for federation purposes, we will need to configure a signing key  to be used by OpenAM . This key is then used to sign metadata. This can be quite a confusing process, so as ever, test test… OpenAM comes with a default test (signing) key that is common to all installations and, as a result, use of this test key should not be considered secure. We’ll create a new test signing certificate and import this into the Java keystore that OpenAM uses.

Note: This is a different Java keystore (JKS) to the one referred in the previous article and used by the web container, Tomcat.

Login to the OpenAM console as amadmin, click on the Configuration tab, then on Servers and Sites and then click on the OpenAM server URL. On the next screen, select the Security tab and scroll down

image

Based on settings from Part 1, the %BASE_DIR% variable that we set in the graphic above alludes to C:/OpenAM. The current certificate alias is set to test, meaning that the server is currently using the default test certificate for token signing. We need to change this. First we’ll need to turn off inheritance so that we can manually change the certificate alias value. This is accomplished by clicking on the Inheritance Settings  button in the top left corner.

image

On the subsequent screen, select the Uncheck the Certificate Alias option.

image

This now enables us to change the Certificate Alias to be used for Token signing from the Test certificate to something else.

image

In this example, we’ll switch the alias and call it openam token signing cert..

image

OpenAM needs to reference keys and certificates for the hosted server instance. This includes a key pair for the host running OpenAM in a JKS format. Under the JDK in the BIN folder is the Java keytool file. Using this tool we’ll now create a new Java Keystore (JKS) to replace the default one.

image

The certificate properties (Name, OU, City, State, Postcode/ZIP, X500 code etc.) will be asked for when the tool runs. Note that we can also create a keystore in tools such as Portecle or Keytool UI if we so choose. Whichever route you select, both will require the keystore to be protected with a password to access the store and also a password for individual keys. These passwords must be encoded with OpenAM, and the information therein stored in the files .keypass and .storepass (these files live in the OpenAM configuration directory).

We can encode the password a couple of ways.

Option 1: Encoding Servlet

There’s an encoding servlet at https://idp.mydomain.com/openam/encode.jsp  as well as command-line tools. This encoding servlet allows for a quick and simple way to encode a password for the .keypass and .storepass files. For example, let’s use the example password of fubarfubar

image

Click on the Encode button.

image

Cut and paste the encrypted password string from the webpage into a text file, e.g. MYPASSWORD.TXT. If you’d prefer not to use the ENCODE.JSP option, read on….

Option 2 : OpenAM SSO Admin Tools

Download the OpenAM tools from the ForgeRock website and extract them into a folder (e.g. C:\Tools).

NOTE: These tools can be used after we first set our JAVA_HOME environment variable.

image

In the example below, SETUP is being run from the tools folder, and when queried for I’ve provided the configuration path information for the OpenAM server, Debug and Log directories.

image

Once the tools are installed, I’d recommend adding the BIN folder to the PATH environment variable. It’s useful to be able to call them from other locations when performing administration via the command-line.

image

With the tools setup we can also call the ampassword utility to generate an encoded sequence. Using the same example as the GUI, I first created a file with the password fubarfubar in it and then call the encode parameter.

C:\temp>type test.txt
fubarfubar
C:\temp>ampassword -e test.txt
AQICyRJQ1CNPI3GMU0vBz2oq3IW8xcKf31eG

The encoded text can be cut and pasted into notepad and then saved as .keypass and .storepass. in the OpenAM configuration folder.

  1. Drop to the OpenAM configuration folder (C:\OpenAM\OpenAM)
  2. Create a folder called BACKUP and copy the original .keypass and .storepass and  keystore.jks into this BACKUP folder.
  3. Copy the JKS file (keystore.jks) created in C:\TEMP earlier to the configuration folder, overwriting the existing JKS
  4. Copy MYPASSWORD.TXT to .keypass and .storepass overwriting the default files.
  5. Restart the Apache Tomcat service.

We can validate whether the signing key is defined correctly by selecting the Create Hosted Identity Provider option on the Common Tasks screen.

image

On the metadata screen, select the Signing Key dropdown box and if the token signing cert appears (no errors), we’re good…..

image

Once we have a proper token signing certificate, we can start setting up OpenAM as an Identity Provider (IdP). OpenAM and AD FS can be linked up in a couple of ways via:

  • SAML 2.0

  • WS-Federation

In this example, we’ll use OpenAM as a SAML 2 Identity Provider (IdP) and AD FS 2.0 as a SAML 2.0 Service Provider (SP). From the metadata screen previously, let’s fill in the necessary details:

image

We need to create a Circle of Trust (COT). A circle of trust is a collection of Identity and Service Providers within OpenAM that engage in identity federation.  It becomes an authentication domain shared between partners, typically one or more service providers and an identity provider, where the parties can communicate in a secure and seamless manner. We can create a circle of trust (COT) manually, or, as in the above example,  during the IdP creation process.

I’ve selected the signing key from earlier, entered the URL for my Identity Provider (IdP) and created a new circle of trust (COT) called ADFS2. In this case, we will have a COT between a SAML 2.0 Identity Provider (OpenAM) and a SAML 2.0 Service Provider (AD FS 2.0).

image

Click on the Register a Remote Server Provider link.

image_thumb6

On the ensuing screen, change the radio button to File when asked for where the metadata file resides. To make the metadata from AD FS understandable to OpenAM we need to trim the information provided by its federation service, so that we retain only the entity identity and descriptor information within the federation metadata XML that is relevant to SAML 2.0 Service Provider (SP) descriptors.  In other words, anything with WS-Trust material in needs to go….

To do this, obtain a copy of the federation metadata file by pointing to the AD FS metadata, e.g:

https://sts.mydomain.com/FederationMetadata/2007-06/FederationMetadata.xml

  1. Download the XML document and save it to file on your desktop / workspace.
  2. Create a copy of the file (let’s call it SPDATA.XML)
  3. Open SPDATA.XML with an XML Editor (or Notepad if you’re feeling brave)
  4. Remove the section beginning <ds:Signature .. ending at </RoleDescriptor>, i.e. all XML tags between EntityDescriptorID and SPSSODescriptor.
  5. Keep the <SPSSODescriptor> </SPSSODescriptor> section. 
  6. Remove  the <IDPSSODescriptor> </IDPSSODescriptor> section.
  7. Keep the remainder of the remaining metadata to end-of-file.
  8. Save the SPDATA.XML file
  9. Check that the file is not corrupted by opening the XML file via IE.

The SPDATA.XML file can now be uploaded to OpenAM

image_thumb35

Click the Upload button to upload the file.

image_thumb11

The file should then upload successfully, otherwise it’s likely a formatting error in the XML file. in which case, try opening it in a browser and see whether you get an error about a corrupt / incorrectly formatted XML file.  Repeat and rinse …….. Smile

Next up, the OpenAM Identity Provider configuration and AD FS 2.0 Service Provider …..

ForgeRock OpenAM 9.5.3 and AD FS 2.0 Integration : Part 1

OpenAM, previously OpenSSO, is a commercial grade open source offering from Forgerock (www.forgerock.com). It provides conventional access management capability using agents, as well as federation and web services single sign-on (SSO). In the coming posts we’ll look at integrating OpenAM with Active Directory Federation Services using federated identities with SAML 2.0. Specifically, we’ll look at using OpenAM as a SAML 2.0 Identity Provider (IdP) and AD FS 2.0 as a SAML 2.0 Service Provider (SP). This is a fairly common configuration for organizations that have already deployed OpenAM and now need to integrate their access management product with the Microsoft claims aware application landscape.

OpenAM is a Java-based web archive (WAR) application, so we’ll need to install both a Java SDK and a Java servlet web container on which it can run. I’m using the Oracle 1.6.0.x JDK for Windows (x64) and Apache Tomcat 6.0.x  as my web container in this example, although platforms such as Glassfish, JBoss, Websphere, Weblogic are eminently useable.

For expediency, Windows is being used here as the testing platform.

Apache Tomcat 6.0.x Configuration

This is a quick walk-thru and (relatively) barebones explanation of the Tomcat server configuration.  If you’re unfamiliar with Tomcat then have a look at the Apache site wiki (http://wiki.apache.org/tomcat/FrontPage).

In this example, the x64 version of Tomcat 6.x is being installed under Windows 2008 R2. Once installation is complete, run the service.bat file from the BIN folder to install Tomcat as a service.

Usage: service.bat install/remove [service_name]

C:\apache-tomcat-6.0.xx\bin>service install
Installing the service ‘Tomcat6’ …
Using CATALINA_HOME:    “C:\apache-tomcat-6.0.xx”
Using CATALINA_BASE:    “C:\apache-tomcat-6.0.xx”
Using JAVA_HOME:        “”
Using JVM:              “auto”
The service ‘Tomcat6’ has been installed.

One thing that does need modifying is the amount of memory available to the Java Heap space and the PermGen space. Normally this is done through the CATALINA.SH file. However,  since we’re running Tomcat under Windows as a service, this can be changed using the TOMCAT6.EXE  file in the BIN folder.

tomcat6 //US//Tomcat6 –JvmMx 1256 ++JvmOptions=”-XX:MaxPermSize=256m”

The label //US//Tomcat6 updates the existing server parameter. Here we’re increasing the maximum heap size to 1256.  Since AD FS 2.0 is involved, the Tomcat web container also needs to be using SSL. We’ll need to customize the SERVER.XML within Tomcat to support the use of HTTPS with a certificate. In the example below we’re using a wildcard certificate (keyAlias)

<Connector port=”443″
protocol=”org.apache.coyote.http11.Http11Protocol”
SSLEnabled=”true”
maxThreads=”200″
scheme=”https”
secure=”true”
keystorefile=”C:/.keystore”
keystorePass=”changeit”
keyAlias=”*.mydomain.com”
clientAuth=”false”
sslProtocol=”TLS” />

The keystorefile directive uses Unix paths, although drive letter literals are accepted.  Again, this can be a bit overwhelming at first so a read of the Tomcat SSL Configuration HOW-TO may be advised if SSL/Tomcat is something new.

http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html

Tomcat, in this configuration, is using a Java keystore (JKS) to store digital certificates, within which will reside our wildcard certificate for web server authentication. Some form of keytool utility to import the certificate with private key (PKCS#12 file) is required. There are various Java keytool progs out there. Here we’re using Portecle, available off SourceForge:

http://portecle.sourceforge.net/

Portecle can also be used to import intermediate certificates into the core Java certificate store, should your third-party certificate provider have an extended certificate chain. This file can be found under the Java program path /jre/lib/security/cacerts

OpenAM Configuration

The latest OpenAM files are available from the Forgerock site. The OpenAM ZIP file contains a deployable-war directory containing an opensso.war file. This file can be dropped under the WEBAPPS folder of the Tomcat application server. Here we’ve renamed the file to openam.war in the process of copying it over as this becomes the Server URI path for logon. Restarting the Tomcat services will expand and deploy the WAR file. 

OpenAM comes with an embedded LDAP server which can be used simultaneously for storing identities and also as a configure store/repository.  This is a Java-based LDAPv3 compliant open-source directory, formerly known as OpenDS, and delivered by Forgerock under the OpenDJ moniker. We’ll use an embedded configuration store in this example.

1. Create a host record (A) record in your local DNS for the name of the OpenAM server or create a loopback entry in your hosts file under system32/drivers/etc, e.g. 127.0.0.1 idp.mydomain.com.

2. Point your browser to https://idp.mydomain.com/openam. The configuration options wizard will begin. Select Create New Configuration

image

3. Enter a password for the default administrator user (amAdmin). is the default administrative/super user used for administration of OpenAM.

image

4. Enter a server URL for OpenAM (e.g. https://idp.mydomain.com:443) and cookie domain (.mydomain.com)

image

5. Use the embedded (OpenAM) configuration data store.

image

6. Select OpenAM as the User Data Store (this is a development/test environment). In a production environment, one of the other LDAP user stores should be used.

image

7. This is a development/test environment, it’s not behind a load-balancer, hence the No selection.

image

8. Enter a password to be used by OpenAM Policy Agents and click Next.

image

9. Review the configuration summary and click Create Configuration when ready.

image

10. OpenAM configuration should now begin.

image

11. Once setup is complete, reboot the server.

12. Launch a browser and point it the OpenAM instance, e.g. https://idp.mydomain.com/openam. Login with the amadmin account and the password chosen earlier.

image

13. The common tasks wizard screen will appear.

image

In the next article: configuring OpenAM and preparing it for identity federation is the subject.

Good luck!!

Mylo