English
بوابة التحقق الالكتروني
الصفحة الرئيسية
   
 

Authentication Gateway Integration Process

Introduction

This document is a brief description of how you may integrate with PACI Authentication Gateway. The Authentication Gateway as of the current version 1.0, it is capable of integrating through SAML IdP.

Any client wants to connect to the IdP needs to have a SAML2.0 Service Provider (SP). SAML is a well-established open standard provided by OASIS, the https://www.oasis-open.org/standards#samlv2.0 have a full list of the documents that defines the standard.

What is SAML 2.0 ?

It stands for Security Assertion Markup Language version 2.0, which is an XML-based protocol that uses security tokens containing assertions and/or attributes to pass information about a principal (usually an end user) between an identity provider and a web service. SAML 2.0 enables web-based authentication and authorization scenarios including single sign-on (SSO).

The critical aspects of SAML 2.0 are covered in detail in the official documents SAMLConform, SAMLCore, SAMLBind, and SAMLProf.

SAML 2.0� is divided into 5 main sections that defines the protocol (framework) of SAML itself. Implementations of the standard might vary a lot according to scenario of usage, in the next section we will give you an overview as well as simple insight information about SAML 2.0.

You may go through the standard is in the OASIS document for full details about the subject.

SAML Protocol

The SAML protocol defines the messages that are exchanged within the framework. �

SAML 2.0 Assertions

As noted SAML is an XML based protocol, SAML exchange of assertion information including the asserted info as well as predefined attributes between SAML parties which will help one party (Service Provider) to make a specific decision, this information exchange� is based on what is called a SAML assertion.

SAML assertion is basically an XML assertion based on a specific XSD. Parties in a SAML transactions predefine the exact options of the assertion so that XML document� exchanged� follows a specific rules that are supported by protocol.

The protocol is so huge such that some parts of it might not be compliant between bearer implementation software.� There is also a room for extensibility outside the protocol itself.

SAML 2.0 Protocols

Assertion Query and Request Protocol

This section defines messages and processing rules for requesting existing assertions by reference or querying for assertions by subject and statement type.

 

Authentication Request Protocol

All SAML requests are of types that are derived from the abstract RequestAbstractType complex type and All SAML responses are of types that are derived from the StatusResponseType complex type. The protocol describe the aspect of fields in both XML types. And their effect on the exchange protocol.

Artifact Resolution Protocol

When a principal (or an agent acting on the principal's behalf) wishes to obtain assertions containing authentication statements to establish a security context at one or more relying parties, it can use the authentication request protocol to send an �Authentication Request (RequestAbstractType) message element to a SAML authority and request that it return a Response (StatusResponseType) �message containing one or more such assertions. Such assertions MAY contain additional statements of any type, but at least one assertion MUST contain at least one authentication statement. A SAML authority that supports this protocol is also termed an identity provider.

Apart from this requirement, the specific contents of the returned assertions depend on the profile or context of use. Also, the exact means by which the principal or agent authenticates to the identity provider is not specified, though the means of authentication might impact the content of the response. Other issues related to the validation of authentication credentials by the identity provider or any communication between the identity provider and any other entities involved in the authentication process are also out of scope of this protocol.

The descriptions and processing rules in the following sections reference the following actors, many of whom might be the same entity in a particular profile of use:

Requester.

The entity who creates the authentication request and to whom the response is to be returned.

Presenter

The entity who presents the request to the identity provider and either authenticates itself during

the transmission of the message, or relies on an existing security context to establish its identity. If not the requester, the presenter acts as an intermediary between the requester and the responding identity provider.

Requested Subject

The entity about whom one or more assertions are being requested.

Attesting Entity

The entity or entities expected to be able to satisfy one of the Subject Confirmation elements of the resulting assertion(s).

Relying Party

The entity or entities expected to consume the assertion(s) to accomplish a purpose defined by the profile or context of use, generally to establish a security context.

Identity Provider

The entity to whom the presenter gives the request and from whom the presenter receives the response.

 

�Artifact Resolution Protocol

Description: This graphic is explained in the accompanying text.

Process Flow for� artifact SSO with SAML 2.0

1.       A user attempts to access resource protected by SAML 2.0.

2.       The service provider redirects user to an identity provider and includes a SAML artifact referring to the authentication request.

3.       The identity provider gets the authentication request from the service provider over a SOAP channel.

4.       The identity provider queries the user for authentication credentials.

5.       The user or user agent presents the requested credentials.

6.       The identity provider returns the user to the service providers with a SAML artifact referring to the authentication response.

7.       The service provider gets the authentication response from the identity provider over a SOAP channel.

8.       The service provider presents the requested resource to the user.

The artifact resolution protocol provides a mechanism by which SAML protocol messages can be transported in a SAML binding by reference instead of by value. Both requests and responses can be obtained by reference using this specialized protocol. A message sender, instead of binding a message to a transport protocol, sends a small piece of data called an artifact using the binding. An artifact can take a variety of forms, but must support a means by which the receiver can determine who sent it. If the receiver wishes, it can then use this protocol in conjunction with a different (generally synchronous) SAML binding protocol to resolve the artifact into the original protocol message.

The most common use for this mechanism is with bindings that cannot easily carry a message because of size constraints, or to enable a message to be communicated via a secure channel between the SAML requester and responder, avoiding the need for a signature.

Depending on the characteristics of the underlying message being passed by reference, the artifact resolution protocol MAY require protections such as mutual authentication, integrity protection, confidentiality, etc. from the protocol binding used to resolve the artifact. In all cases, the artifact MUST exhibit a single-use semantic such that once it has been successfully resolved, it can no longer be used by any party.

Regardless of the protocol message obtained, the result of resolving an artifact MUST be treated exactly as if the message so obtained had been sent originally in place of the artifact.

Name Identifier Management Protocol

After establishing a name identifier for a principal, an identity provider wishing to change the value and/or format of the identifier that it will use when referring to the principal, or to indicate that a name identifier will no longer be used to refer to the principal, informs service providers of the change by sending them a �Managed Name Request ID� message.

A service provider also uses this message to register or change the Service Provider Provided ID value to be included when the underlying name identifier is used to communicate with it, or to terminate the use of a name identifier between itself and the identity provider.

Note that this protocol is typically not used with "transient" name identifiers, since their value is not intended to be managed on a long term basis.

Single Logout Protocol

The single logout protocol provides a message exchange protocol by which all sessions provided by a particular session authority are near-simultaneously terminated. The single logout protocol is used either when a principal logs out at a session participant or when the principal logs out directly at the session authority. This protocol may also be used to log out a principal due to a timeout. The reason for the logout event can be indicated through the Reason attribute.

The principal may have established authenticated sessions with both the session authority and individual session participants, based on assertions containing authentication statements supplied by the session authority.

When the principal invokes the single logout process at a session participant, the session participant MUST send a logout request message to the session authority that provided the assertion containing the authentication statement related to that session at the session participant.

When either the principal invokes a logout at the session authority, or a session participant sends a logout request to the session authority specifying that principal, the session authority SHOULD send a Logout Request message to each session participant to which it provided assertions containing authentication statements under its current session with the principal, with the exception of the session participant that sent the <LogoutRequest> message to the session authority. It SHOULD attempt to contact as many of these participants as it can using this protocol, terminate its own session with the principal, and finally return a <LogoutResponse> message to the requesting session participant, if any.

Name Identifier Mapping Protocol

When an entity that shares an identifier for a principal with an identity provider wishes to obtain a name identifier for the same principal in a particular format or federation namespace, it can send a request to the identity provider using this protocol.

For example, a service provider that wishes to communicate with another service provider with whom it does not share an identifier for the principal can use an identity provider that shares an identifier for the principal with both service providers to map from its own identifier to a new identifier, generally encrypted, with which it can communicate with the second service provider.

Regardless of the type of identifier involved, the mapped identifier SHOULD be encrypted into a SAML Encrypted ID element unless a specific deployment dictates such protection is unnecessary.

SAML 2.0 Bindings

SAML defines a 5 Bindings between the SAML assertion bearers, which are:

SOAP Binding

In this binding protocol messages are carried inside a SOAP message the binding doesn�t actually define the connection protocol. Any provider must be capable of sending SOAP over http, in Browser Web SSO the browser intuitively cannot call a web service directly so usually SOAP binding happens over http. However the provider might use different ways of binding the protocol which is usually vendor specific.

Reverse SOAP (PAOS) Binding

In this binding protocol the mechanism by which an HTTP requester can advertise the ability to act as a SOAP responder or a SOAP intermediary to a SAML requester. The HTTP requester is able to support a pattern where a SAML request is sent to it in a SOAP envelope in an HTTP response from the SAML requester, and the HTTP requester responds with a SAML response in a SOAP envelope in a subsequent HTTP request.

�This message exchange pattern supports the use case defined in the Enhanced Client or Proxy (ECP),an ECP usually is a specially crafted browser, SSO profile (described in the SAML profiles specification in which the HTTP requester is an intermediary in an authentication exchange.

HTTP Redirect Binding

In this binging SAML protocol messages are often carried directly in the URL query string of an HTTP GET request. Since the length of URLs is limited in practice, consequently the query string, the HTTP Redirect binding is suitable for short messages.� There is other information related to the Redirect binding and will find it all in the standard documentation.

HTTP POST Binding

In this binding SAML messages are often carried over HTTP POST Request. Unlike the Redirect binding there is no limitation on message size, the message doesn�t have to be compressed. POST binding is considered safer than Redirect binding.

HTTP Artifact Binding

In the HTTP Artifact binding, the SAML request, the SAML response, or both are transmitted by reference using a small stand-in called an artifact. A separate, synchronous binding, such as the SAML SOAP binding, is used to exchange the artifact for the actual protocol message using the artifact resolution protocol defined in the SAML assertions and protocols specification .

This binding MAY be composed with the HTTP Redirect binding and/or the HTTP POST binding to transmit request and response messages in a single protocol exchange using two different bindings.

URI binding

URIs are a protocol-independent means of referring to a resource. This binding is not a general SAML request/response binding, but rather supports the encapsulation of <samlp:AssertionIDRequest> message with a single <saml:AssertionIDRef> into the resolution of a URI. The result of a successful request is a SAML <saml:Assertion> element (but not a complete SAML response).

Like SOAP, URI resolution can occur over multiple underlying transports. This binding has transporting dependent aspects, but also calls out the use of HTTP with SSL 3.0 [SSL3] or TLS 1.0 [RFC2246] as REQUIRED (mandatory to implement).

SAML 2.0 Profiles

OASIS has provided a set of specific profiles in the standard, these profiles may or may not be implemented by a SAML provider. Here we will briefly talk about the profiles, but you may go through the SAML standard to understand more about these profiles noting that the most used profile is the Browser SSO profile which PACI supports.

 

 

Web Browser SSO Profile

A typical Web browser Single sign on profile might be as follows in the picture

Description: Image:saml2idp-1.png

Process Flow for Browser SSO with SAML 2.0

1.       A user attempts to access resource protected by SAML 2.0.

2.       The service provider redirects user to an identity provider for authentication.

3.       The identity provider queries user for authentication credentials.

4.       The user or user agent presents the requested credentials.

5.       The identity provider returns the user to the service providers with an authentication response.

6.       The Assertion consumer service checks, decrypts and/or resolute the response.

7.       The service provider presents the requested resource to the user.

 

In the scenario supported by the web browser SSO profile, a web user either accesses a resource at a service provider, or accesses an identity provider such that the service provider and desired resource are understood or implicit. The web user authenticates (or has already authenticated) to the identity provider, which then produces an authentication assertion (possibly with input from the service provider) and the service provider consumes the assertion to establish a security context for the web user. During this process, a name identifier might also be established between the providers for the principal, subject to the parameters of the interaction and the consent of the parties.

To implement this scenario, a profile of the SAML Authentication Request protocol is used, in conjunction with the HTTP Redirect, HTTP POST and HTTP Artifact bindings. It is assumed that the user is using a standard commercial browser and can authenticate to the identity provider by some means outside the scope of SAML.

Enhanced Client or Proxy profile

An enhanced client or proxy (ECP) is a system (usually a special kind of browsers) entity that knows how to contact an appropriate identity provider, possibly in a context-dependent fashion, and also supports the Reverse SOAP (PAOS) binding.

An example scenario enabled by this profile is as follows: A principal, wielding an ECP, uses it to either access a resource at a service provider, or access an identity provider such that the service provider and desired resource are understood or implicit. The principal authenticates (or has already authenticated) with the identity provider, which then produces an authentication assertion (possibly with input from the service provider). The service provider then consumes the assertion and subsequently establishes a security context for the principal. During this process, a name identifier might also be established between the providers for the principal, subject to the parameters of the interaction and the consent of the principal.

This profile is based on the SAML Authentication Request protocol in conjunction with the PAOS binding.

The means by which a principal authenticates with an identity provider is outside of the scope of SAML.

Identity Provider Discovery Profile

This profile by which a service provider can discover which identity providers a principal is using with the Web Browser SSO profile. In deployments having more than one identity provider, service providers need a means to discover which identity provider(s) a principal uses. The discovery

profile relies on a cookie that is written in a domain that is common between identity providers and service providers in a deployment. The domain that the deployment predetermines is known as the common domain in this profile, and the cookie containing the list of identity providers is known as the common domain cookie.

Which entities host web servers in the common domain is a deployment issue and is outside the scope of this profile.

Assertion Query/Request Profile

The Assertion Query/Request Profile is a general profile that accommodates numerous types of so-called queries using the following SAML 2.0 elements:

  • the <samlp:AssertionIDRequest> element, which is used to request an assertion given its unique identifier (ID)
  • the <samlp:SubjectQuery> element, which is an abstract extension point that allows new subject-based SAML queries to be defined
  • the <samlp:AuthnQuery> element, which is used to request existing authentication assertions about a given subject from an Authentication Authority
  • the <samlp:AttributeQuery> element, which is used to request attributes about a given subject from an Attribute Authority
  • the <samlp:AuthzDecisionQuery> element, which is used to request an authorization decision from a trusted third party

The SAML SOAP binding is often used in conjunction with queries.

SAML Attribute Query

The Attribute Query is perhaps the most important type of SAML query. Often a requester, acting on behalf of the principal, queries an identity provider for attributes. Below we give an example of a query issued by a principal directly

Single Logout profile

Description:

Once a principal has authenticated to an identity provider, the authenticating entity may establish a session with the principal (typically by means of a cookie, URL re-writing, or some other implementation specific means). The identity provider may subsequently issue assertions to service providers or other relying parties, based on this authentication event; a relying party may use this to establish its own session with the principal.

In such a situation, the identity provider can act as a session authority and the relying parties as session participants. At some later time, the principal may wish to terminate his or her session either with an individual session participant, or with all session participants in a given session managed by the session authority. The former case is considered out of scope of this specification. The latter case, however, may be satisfied using this profile of the SAML Single Logout protocol.

SAML 2.0 Metadata

This specification further defines profiles for the dynamic exchange of metadata among system entities, which may be useful in some deployments. It is a pretty way the bearers may exchange configuration between them and the protocol defines a secure way for this transactions, noting that this doesn�t mean that metadata should be exchanged remotely but it can.

The Metadata standardized the information exchange for following entities in the framework

1.       �Identity Provider Metadata : Metadata provided by the identity provider

2.       �SSO Service Metadata.

3.       Service Provider Metadata: Metadata provided by the Service provider

4.       Assertion Consumer Service Metadata

PACI as SAML 2.0 Identity provider current capabilities

 

Currently PACI supports most of the SAML protocol aspects, yet to be specific this section defines what actually PACI supports in aspect of bindings and profiles.

Bindings

1-      Redirect Bindings

2-      POST bindings

3-      Artifact bindings

4-      SOAP over HTTP bindings

Supported profiles:

1-      Web browser SSO

2-      Identity provider discovery

3-      Single logout Profile

Attribute exchange capability is important to exchange vital information to service provider that might want to have data from PACI, the SAML framework provides a way to exchange some information,� so in developing the Gateway PACI took in mind that we may exchange attributes for The Metadata standardized the information exchange for fodata, currently the Gateway supports these attributes out of the box.

1-      Civil ID

2-      Arabic Name

3-      English Name

4-      Date of Birth

5-      Country of Birth

6-      Expiry date of card

7-      Expiry date of certificate

8-      An Email address (provided by user)

However more attributes can be exchanged yet this will require approval from PACI Information privacy committee are as well as specific implementation of the SAML protocol, specifically the data must be encrypted and the use of artifact binding is highly encouraged over KIN, these attributes include:

9-      User current address

10-   Family members

11-   Company of employment

12-   Reports from PACI

13-   Other attributes that can be provided from PACI database

 

Integration requirements

 

Here we define regular procedures that any integrator with PACI should follow.

These procedures are as follows:

1-      Find a software application that can implement an SP in SAML 2.0, many ERP providers include this plugin capabilities within the software packages they offer, for instance IBM WebSphere, Oracle Identity Manager and more providers come in this category.

2-      For security �if required� a user should buy a FIPS140-2 appliance which is compliant with their software provider capabilities to store their SP certificate and credentials information.

3-      Send Certificate request to PACI certificate authority which will provide you with a certificate to store in your appliance

4-      Fill in the Application paper with PACI which will include the configuration capability that you require and we support

5-      Sign a Non-disclosure agreement between both bearers.

6-      PACI will send you a signed metadata file that you may use with your SP provider software to configure you application, and/or any technical help you in the integration process