OIF/OSTS Service Information

OIF and OSTS are two products designed to provide Federation capabilities across security domains:
  • Cross domain SSO for browser based Web SSO flows
  • Cross domain Web Services Security (WSS) for SOAP clients and servers via the WS-Trust protocol

Federation between services is based on trust which is established by exchanging

  • X.509 certificates used for sign/verify and encrypt/decrypt the Federation messages
  • Locations of the Federation services
  • SAML 2.0 Metadata if supported by the partners, when SAML 2.0 Federation SSO is used

In this article, I will discuss about the various kinds of information one has to know in order to be able to set up a Federation agreement between OIF and remote partners, including:

  • How to enable OIF/OSTS services
  • SAML/OpenID Identifiers for OIF/OSTS
  • SAML 2.0 Metadata
  • Certificates
  • Service endpoints

Enabling OIF / OSTS Services


OIF/OSTS Enablement

Out of the box, the OIF and OSTS components are disabled in the OAM server, and need to be enabled prior to using them. To enable OIF and/or OSTS, you will need to:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Configuration -> Available Services
  • Enable the components you need

To verify that OIF is correctly enabled, you can attempt to download OIF SAML 2.0 Metadata from
http(s)://oam-runtime-host:oam-runtime-port/oamfed/idp/metadata

OIF Services

After having turned on the OIF component, all OIF services are enabled:

  • IdP
  • SP
  • SAML Attribute Authority
  • SAML Attribute Requester

To selectively enable or disable those above services, use the OIF WLST command configureFederationService():

  • Enter the WLST environment by executing:
    $IAM_ORACLE_HOME/common/bin/wlst.sh
  • Connect to the WLS Admin server:
    connect()
  • Navigate to the Domain Runtime branch:
    domainRuntime()
  • Execute the configureFederationService() command:
    configureFederationService(<SERVICE>, <true/false>)
    • Replace <SERVICE> by idp, sp, attributeresponder or attributerequester
    • Set true to enable the service or false to disable it
    • For example, to disable the SAML Attribute Authority service, execute:
      configureFederationService("attributeresponder", "false")

SAML Issuer / OpenID Realm


When communicating via the SAML protocols, Federation servers identify themselves via the Issuer element in the SAML messages. This is also known as the Entity ID or the Provider ID. This identifier must be unique among partners so that one identifier references a single entity.

In the OpenID 2.0 protocol, the Relying Party or Service Provider can be identified via the Realm element.

OIF

During installation, the Provider ID used in SAML operations and the Realm used in OpenID 2.0 exchanges are set to:

  • SAML Provider ID:
    http://oam-runtime-hostname:oam-runtime-port/oam/fed
  • OpenID 2.0 Realm:
    http://oam-runtime-hostname:oam-runtime-port

To change the Provider ID, perform the following steps:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Configuration -> Federation Settings
  • Set the Provider ID to the desired value
    • Note #1: the Succinct ID which is the SHA-1 hash of the Provider ID and used in SAML Artifact protocol will be re-generated
    • Note #2: after resetting the Provider ID, you will need to notify all the existing partners of the change and redistribute SAML 2.0 Metadata if necessary
  • Apply

OSTS

During installation, the Provider ID used in SAML Issuance Templates is set to:
http://oam-runtime-hostname:oam-runtime-port/oam/fed

  • To change or retrieve the Provider ID from an Issuance Template, perform the following steps:
  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Configuration -> Security Token Service Settings -> Token Issuance Templates
  • Click on the desired SAML Issuance Template
  • Click on the Issuance Properties tab
  • The Provider ID is the Assertion Issuer property. Set the corresponding field to update the Provider ID for this SAML Issuance Template
  • Apply

SAML 2.0 Metadata


The SAML 2.0 SSO protocol define the Metadata XML document which is used by Federation servers to publish all information the partners will need to be aware of in order to exchange SAML 2.0 messages.

The SAML 2.0 Metadata of a Federation server includes:

  • The X.509 signing certificate to allow the remote partner to verify messages signed by the Federation server
  • The X.509 encryption certificate to allow the remote partner to encrypt messages that only the Federation server will be able to decrypt
  • Roles supported by the Federation server:
    • IdP
    • SP
    • SAML Attribute Authority
    • SAML Attribute Requester
  • Services for each of those roles
    • SSO, Logout
    • Type of SAML binding used to communicate with those services (HTTP-Redirect, HTTP-POST, Artifact, SOAP…)
    • Location indicating the endpoint where a service is published
    • ResponseLocation indicating the endpoint were a service is published for response messages

The OIF Metadata can be retrieved from the OAM Administration Console:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Configuration -> Federation Settings
  • Click on the Export Metadata button
  • Save the file on your local computer

The OIF Metadata can also be retrieved by accessing a URL on the OAM/OIF runtime server:
http://oam-runtime-host:oam-runtime-port/oamfed/idp/metadata

Note: it is possible to generate OIF Metadata for specific signing and encryption keys by using the following URL (read my next article about Key Management in OIF/OSTS for more information)
http://oam-runtime-host:oam-runtime-port/oamfed/idp/metadata?signid=<SIGN_KEYENTRY_ID>&encid=<ENC_KEYENTRY_ID>

  • The signid query parameter contains the key entry ID for the signing certificate. Replace <SIGN_KEYENTRY_ID>
  • The encid query parameter contains the key entry ID for the encryption certificate. Replace <SIGN_KEYENTRY_ID>
  • An example would be:
    http://oam.com/oamfed/idp/metadata?signid=osts_signing&encid=osts_encryption

Certificates


For SAML 2.0 partners not supporting the consumption of SAML 2.0 Metadata, or for SAML 1.1 partner or even STS partners, the administrator will need to provide the signing certificate and possibly the encryption certificate as standalone files.

The OIF/OSTS Settings section in the administration console lists the key entries used by the system (read my next article about Key Management in OIF/OSTS for more information)

To view the current key entries known to OIF/OSTS:

  1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  2. Navigate to Configuration -> Federation Settings / Security Token Service Settings
  3. In the Keystore section, see the list of Key IDs, each representing a key entry in OIF/OSTS, and each referencing a key entry in the OAM Keystore (different key IDs can reference the same key entry in the OAM Keystore)

To retrieve the certificate file of a specific key ID, open a browser and use the following URL to generate the certificate in PEM format:

  • For OIF:
    http://oam-runtime-host:oam-runtime-port/oamfed/idp/cert?id=<KEYENTRY_ID>
    • The id query parameter contains the key entry ID for the certificate. Replace <KEYENTRY_ID>
    • An example would be:
      http://oam.com/oamfed/idp/cert?id=saml-signing   
  • For OSTS:
    http://oam-runtime-host:oam-runtime-port/sts/servlet/samlcert?id=<KEYENTRY_ID>
    • The id query parameter contains the key entry ID for the certificate. Replace <KEYENTRY_ID>
    • An example would be:
      http://oam.com/sts/servlet/samlcert?id=saml-signing

OIF Endpoints


This section will list the various endpoints published by OIF, some specific to a protocol, others protocol agnostic.

Note: it is important to access the OIF services via the public endpoints (load balancer, HTTP reverse proxy…) in order for HTTP cookies set in the browser to be sent back by the browser. In this list, only paths will be listed, not the public protocol/hostname/port.

SAML 2.0

The IdP SAML 2.0 endpoints are:

  • SSO Service to receive AuthnRequest messages
    • HTTP-Redirect binding: /oamfed/idp/samlv20
    • HTTP-POST binding: /oamfed/idp/samlv20
    • SOAP binding for ECP clients: /oamfed/idp/soap
  • Artifact Service for SP to send SOAP ArtifactResolve messages during SSO Artifact: /oamfed/idp/soap
  • Logout Service to receive LogoutRequest and LogoutResponse messages
    • LogoutRequest:
      • HTTP-Redirect binding: /oamfed/idp/samlv20
      • HTTP-POST binding: /oamfed/idp/samlv20
    • LogoutResponse
      • HTTP-Redirect binding: /oamfed/idp/samlv20
      • HTTP-POST binding: /oamfed/idp/samlv20

The SP SAML 2.0 endpoints are:

  • Assertion Consumer Service to receive SAML Assertions
    • HTTP-POST binding: /oam/server/fed/sp/sso
    • Artifact binding: /oam/server/fed/sp/sso
  • Logout Service to receive LogoutRequest and LogoutResponse messages
    • LogoutRequest:
      • HTTP-Redirect binding: /oamfed/sp/samlv20
      • HTTP-POST binding: /oamfed/sp/samlv20
    • LogoutResponse
      • HTTP-Redirect binding: /oamfed/sp/samlv20
      • HTTP-POST binding: /oamfed/sp/samlv20

The SAML 2.0 Attribute Authority/Responder endpoints are:

  • SOAP Service for SAML Attribute Requester to send SOAP Attribute Query messages: /oamfed/aa/soap

The SAML 2.0 Attribute Requester does not publish any endpoint.

SAML 1.1

The IdP SAML 1.1 endpoints are:

  • SSO Service to start SAML 1.1 Federation SSO
    • URL: /oamfed/idp/samlv11sso
    • Query parameters (URL encode properly the query parameter values)
      • providerid: indicates the SP partner name or SP Provider ID with which to start Federation SSO
      • TARGET: indicates the value to send as the TARGET to the SP. Typically, this will contain the URL where the user should be redirected after the Federation SSO operation
  • Artifact Service for SP to send SOAP ArtifactResolve messages during SSO Artifact: /oamfed/idp/soapv11

The SP SAML 1.1 endpoints are:

  • Assertion Consumer Service to receive SAML Assertions
    • URL: /oam/server/fed/sp/sso

The SAML 1.1 Attribute Authority/Responder endpoints are:

  • SOAP Service for SAML Attribute Requester to send SOAP Attribute Query messages: /oamfed/aa/soapv11

The SAML 1.1 Attribute Requester does not publish any endpoint.

OpenID 2.0

The IdP OpenID 2.0 endpoints are:

  • SSO Service to receive OpenID Authn Request messages from RPs
    • URL: /oamfed/idp/openidv20
  • Discovery Service where XRDS is published:
    • URL: /oamfed/idp/openidv20

The SP OpenID 2.0 endpoints are:

  • SSO Service to receive OpenID Authn Response messages from OPs
    • URL: /oam/server/fed/sp/sso
  • RP Realm: see SAML Issuer / OpenID Realm section about that identifier

Other Services

There are a few services that are protocol agnostic:

  • IdP initiated SSO Service
    • URL: /oamfed/idp/initiatesso
    • Query parameters (URL encode properly the query parameter values)
      • providerid: indicates the SP partner name or SP Provider ID with which to start Federation SSO
      • returnurl: indicates where the user should be redirected after the Federation SSO operation
  • SP initiated SSO
  • URL: /oamfed/sp/initiatesso
    • Query parameters (URL encode properly the query parameter values)
      • providerid: indicates the IdP partner name or IdP Provider ID with which to start Federation SSO
      • returnurl: indicates where the user should be redirected after the Federation SSO operation
  • Test SP which allows you to test OIF/SP with a remote IdP partner
    • URL: /oamfed/user/testspsso
    • Note: prior to using this service, you must enable it via the configureTestSPEngine() command:
      • Enter the WLST environment by executing:
        $IAM_ORACLE_HOME/common/bin/wlst.sh
      • Connect to the WLS Admin server:
        connect()
      • Navigate to the Domain Runtime branch:
        domainRuntime()
      • Execute the configureTestSPEngine () command:
        configureTestSPEngine(<true/false>)
        • Set true to enable the service or false to disable it
        • For example, to enable the Test SP service, execute:
          configureTestSPEngine("true")

OSTS Endpoints

OSTS publishes SOAP endpoints based on how the Security Token Service is configured.

The Security Token Service -> Endpoints section in the OAM Administration Console lists the endpoints defined for OSTS and how they are protected by the OWSM Agent

For a given endpoint (for example /wss11user), the following URLs are published:

  • Over SOAP 1.2: /sts/wss11user
  • WSDL for operations over SOAP 1.2: /sts/wss11user?wsdl
  • Over SOAP 1.1: /sts/wss11user/soap11
  • WSDL for operations over SOAP 1.1: /sts/wss11user/soap11?wsdl

In the next article, I will discuss about PKI Key and Certificate management in OIF/OSTS
Cheers,
Damien Carru

Comments:

Post a Comment:
  • HTML Syntax: NOT allowed
About

Damien Carru is a member of the Oracle Identity Management organization, focusing on Federation and SSO. This blog will cover Federation use cases involving Oracle Access Manager, Oracle Identity Federation and Oracle Security Token Service

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
5
6
8
9
10
12
13
15
16
17
19
20
22
23
24
25
26
27
28
29
30
   
       
Today