This document demonstrates the setup of a simple federation with OpenSSO. The federation consists of an Identity Provider(!IdP), hosted on idp.e-taxonomy.eu and managed with OpenSSO. Additionally, the federation includes a Service Provider(SP), hosted on sp.e-taxonomy.eu using a *TODO*Shibboleth v2.1 Service Provider setup.
Currently, the OpenSSO command-line administrator tool does not work as expected. Thus, the description relies on the graphical OpenSSO console. We will extend this description for the command-line tool later.
Also, OpenSSO provides an inofficial administration console (ssoadm.jsp e.g. https://idp.e-taxonomy.eu/opensso/ssoadm.jsp). It offers quite the same commands as the command-line administrator tool, but can not be used for scripting.
Keys and Certificates¶
If, of course, we want to enable OpenSSO for a secure federation setup (includes request and response signing), OpenSSO needs to reference keys and certificates for the hosted instance. For that, OpenSSO supports Java keystores and we should start to create one. It should include a key pair for the host running OpenSSO, and trusted CA certificates of federation members, such as Identity or Service Providers.
IBM KeyMan is a comfortable Java keystore management tool. In particular, it can be used to create Java Keystores through importing of PEM key and certificate files. On the idp site, these files can be found in /etc/ssl/private and /etc/ssl/certs respectively. So, using KeyMan, import these files and copy the resulting keystore to the OpenSSO configuration(e.g. /etc/opensso/opensso/idp.e-taxonomy.eu.jks). Don't forget to create an alias for your private keys and and trusted CA certificates (e.g. _idp.e-taxonomy.eu,EDITRootCA, EDITServerCA).
When saving the keystore, KeyMan asks you for a password to protect your keystore/truststore. These passwords must be encoded with OpenSSO. So login as amadmin first and direct your browser to https://idp.e-taxonomy.eu/opensso/encode.jsp. Create two files in the opensso configuration (e.g. /etc/opensso/opensso/idp.e-taxonomy.eu.storepass and /etc/opensso/opensso/idp.e-taxonomy.eu.keypass) and paste the result of the encoding into them.
Next, we must change the default configuration, so that OpenSSO will recognise the new keystore. Go to https://idp.e-taxonomy.eu/opensso/ and login as amAdmin, Select Configuration first, then Servers and Sites.
Press on Default Server Settings and select Key Store.
[!OpenSSO-Configuration-Servers|and Sites-Edit Server Default-Security.png!]
There, modify the file locations for Keystore File, Keystore Password File and Private Key Password File according to the files name of your Java Keystore (see above). Certificate Alias is the alias in the Java Keystore for the private key (e.g. idp.e-taxonomy.eu). In our OpenSSO Installation %BASE_DIR% equals to /etc/opensso, %SERVER_URI% equals to opensso.
[!OpenSSO-Configuration-Servers|and Sites-Edit Server Default-Security-Key Store.png!]
Finally, press Log out and restart Tomcat. This enables OpenSSO to read the new configuration.
We should create a realm to organise configuration information like users, groups, data stores and other data. OpenSSO comes with a top level realm, which should be preserved for the OpenSSO configuration itself. So, we create a realm for EDIT, and add some users and groups to that realm first. Later, we will also assign our EDIT federation to that realm.
To create a new realm, go to the main menu and select the tab Access Control. Then, press New to create a new realm.
Here, enter the name of the new realm(e.g. EDIT). Optionally, assign an alias of the realm to a DNS domain (e.g. e-taxonomy.eu).
Now, the EDIT realm should be visible.
Create Users and Groups¶
Next, we should add some users to the newly created EDIT realm. Click on the EDIT realm and select the tab Subjects. There, you will have the opportunity to create users and groups assigned to the EDIT realm.
Create Hosted Identity Provider¶
Now, we can proceed to configure our OpenSSO host as Identity Provider. Therefore, on the main menu, select the Common Tasks tab and press on Create Hosted Identity Provider.
[!OpenSSO-Common|Tasks-Create Hosted Identity Provider.png!]
First, you should select a realm to which the Identity Provider should be assigned to. Then, adopt the metadata Name. You should be able to select the private key alias, which you have entered when configuring [#KeysandCertificates|Keys and Certificates]. Finally, choose a name for your federation (e.g. EDIT) and enter it in the field New Circle of Trust). Circle of Trust (COT) is term OpenSSO uses instead of federation.
[!OpenSSO-Common|Tasks-Create Hosted Identity Provider-Create SAMLv2 IdP on this Server.png!]
Additionally, you can add mappings for some default attributes, the Identity Provider will release on request of Service Providers. Note, that Shibboleth Service Provider expect the full attribute URI to accept an attribute within an assertion (e.g. urn:mace:dir:attribute-def:eduPersonPrincipalName). Attributes can be revised at any time through the Federation tab in the main menu.
If you like, you may proceed with the registration of Remote Service Providers directly.
Register Remote Service Provider¶
This step presumes, that there is a running Shibboleth v2.x service provider. We use the Service Provider on https://sp.e-taxonomy.eu
On the main menu, select the Common Tasks tab and press on Register Remote Service Provider.
[!OpenSSO-Common|Tasks-Register Remote Service Provider.png!]
First, assign the Service Provider to an existing realm. Since SAML/Shibboleth v2.x, metadata can also exchanged via specific URL besides the Service Provider as well as the Identity Provider. The default location to access SP metadata is /Shibboleth.sso/Metadata (e.g. https://sp.e-taxonomy.eu/Shibboleth.sso/Metadata). Therefore, select the URL button and enter the metadata URL for the service provider to be registered.
Add the Remote Service Provider to an existing federation (i.e. Circle of Trust).
[!OpenSSO-Common|Tasks-Register Remote Service Provider-Create SAMLv2 Remote SP.png!]
If, the SP to be registered does not offer his metadata via URL, you may also catch the XML-metadata from the service provider, and provide OpenSSO with the corresponding local file location instead of the URL. For that, you will have to edit the Shibboleth SP metadata (/Shibboleth.sso/Metadata), and remove all the XML digital signature AND the md:Extensions nodes.
Press Configure, and you will be redirected to the Common Tasks main menu. You may select Test Federation Connectivity to check if your federation is connected.
Any further federation management task can be accessed under the Federation tab in the main menu.