eIAM Access Request (ARQ)
eIAM AccessRequest Description
The AccessRequest application provides a Web GUI interface in the form of a Web application to applications protected by eIAM. For applications within the networks of the Federal Administration, the call of eIAM-AccessRequest is automatically triggered by the absence of the gross-granular role. Applications outside the networks of the Federal Administration must call up the eIAM-AccessRequest themselves. They can do this via an HTTP GET request with the query parameters described below. To do this, the application can show the user an information page with a corresponding link to the "AccessRequest" application with the corresponding parameters or it can automatically redirect the user to the "AccessRequest" application in the case of missing access rights. Furthermore, it is possible for users who are already authorised for the application to request additional authorisations from within the application. For this purpose, the user can be offered a link within the application with which he can call up eIAM-Access.When implementing the link independently, particular attention must be paid to usability.
The eIAM-AccessRequest application supports two use cases:
- In the first use case, an email is sent to the person responsible for authorisation in the corresponding application (BVA) during the course of the access request, thus triggering a workflow. They assign the necessary authorisations. The authorisation roles are not assigned automatically.
- In the second use case, a so-called "AutoRole scenario" is supported. In this mode, predefined roles can be automatically assigned to the user for the application in the eIAM-AM. No e-mail notification is sent in this scenario. This mode can be used if the application wants to capture specific identity attributes. This makes it possible for the user to access a form within the specialist application where they can enter application-specific attributes.
eIAM AccessRequest URL
The AccessRequest application is called via the eIAM Web PEP. The absolute URI to be used is therefore relative to the eIAM-Web PEP used:/_pep/accessRequest
Example call URL from the perspective of the user's browser:
https://www.gate.amt.admin.ch/_pep/accessRequest
eIAM-AccessRequest Query Arguments
For applications hosted within the Federal Administration networks, eIAM-AccessRequest is parameterised and controlled by the eIAM-Web PEP before the application. When accessing the application "AccessRequest" from externally hosted applications, some query arguments must be passed to this request in order to define to which application the access request should be made and how the user can be sent back to the application after the access request has been completed.| argument | description |
| returnURL | - Address to which the user is directed after the access request is completed. The address must be URL-encoded. - Either returnURL or returnURLb64 must be defined so that a return to the application is possible. - It is important to understand, especially in the "AutoRole" scenario, that the user will only receive the requested roles after logging out of the application and the eIAM-Web PEP and logging in again. Therefore, the returnURL should direct the user to a page in the application that informs him that he has to log in again or the returnURL points to the logout URL of the application and thereby triggers a SAML single logout of the user's session on the eIAM-Web PEP as well. |
| returnURLb64 | - Address to which the user is directed after the access request has been completed. This must be Base64 encoded. - Either returnURL or returnURLb64 must be defined so that a return to the application is possible. - It is important to understand, especially in the "AutoRole" scenario, that the user will only receive the requested roles after logging out of the application and the eIAM-Web PEP and logging in again. Therefore, the returnURLb64 should direct the user to a page in the application that informs him that he has to log in again or the returnURLb64 points to the logout URL of the application and thereby triggers a SAML single logout of the user's session on the eIAM-Web PEP as well. |
| appl | - Application in the eIAM-AM for which the access request is to be made. - Either applURL or appl MUST be defined to identify the application for the request. |
| applURL | - URL of the application for which the access request is to be made. - Either applURL or appl MUST be defined to identify the application for the request. - The address must be URL-encoded. |
| client (optional) | - Client to which the access request should apply. - Can be used, for example, to suppress client selection for applications that are assigned to multiple clients. |
| CICD (optional) | - The CICD determines the appearance of the displayed masks. |
eIAM AccessRequest Example
In the following example, the application "AccessRequest" is called up in the production environment via the eIAM-Web PEP www.gate.bit.admin.ch to trigger an access request for the user for the application "Statistika" of the client "BIT". After the access request has been made, the user is to be redirected back to the URL https://www.externalhost.admin.ch/statistika/private/logout.do of the application hosted outside the networks of the Federal Administration.Call:
https://www.gate.amt.admin.ch/_pep/accessRequest? applURL=https%3A%2F%2Fwww.gate.bit.admin.ch%2Fstatistika%2Fprivate%2F&
client=BIT&returnURLb64=aHR0cHM6Ly93d3cuZXh0ZXJuYWxob3N0LmFkbWluLmNoL
3N0YXRpc3Rpa2EvcHJpdmF0ZS9sb2dvdXQuZG8
eIAM-AccessRequest Access Request Flow
This chapter explains the procedure for a user to access an application hosted outside the networks of the Federal Administration to which he is not yet authorised.The illustration below shows the procedure for a user to access an external application to which he is not yet authorised. The scenario of the external application was chosen because it represents the more complex case.
Access to the application triggers authentication of the user. After authentication, the application checks whether the user is authorised for the application.
If the user is not authorised for the application, the external application triggers the access request with the feature "AccessRequest" of the service eIAM.
-
- Access of a user to an application to which he is not yet authorised
The eIAM AccessRequest first checks whether identity references have already been recorded for the user in the eIAM-AM. This is done both in the eIAM-AM superclient and in the eIAM-AM access client. Any identity references that are still missing are created automatically.
The correct application and the corresponding profile policy in the eIAM-AM Access client are determined by means of the parameters specified in the eIAM-Access request. This may require user interaction in the form of a selection by the user if several applications or clients come into question.
The configuration for the eIAM AccessRequest is read from the profile policy of the application in the eIAM-AM, e.g. whether and which roles should be assigned automatically. It is also determined which information is displayed to the user as a completion message. This can either be information that access is already possible after logging out and logging in again or that an administrator must first process the access request and the user is then informed accordingly by the administrator. In the closing message, the user is shown a link with which he can return to the application, if a return address has been given.
The new roles assigned after the AccessRequest can only be used when the user logs off and logs on again. Only then are the assigned roles transferred to the new SAML assertion and are available to the eIAM-Web PEP and the application. For applications that use the eIAM-Web service and are thus protected by an eIAM PEP, this new logon is triggered directly by the eIAM-Web PEP. For external applications that are not behind the eIAM-Web PEP, this must be triggered by the application itself. The return address to the application MUST therefore point to the logout URL of the application in the "AutoRole scenario".