This component can be used in Frontends to allow Authorised Delegation of users.
Include the following dependency in your SBT build
resolvers += Resolver.bintrayRepo("hmrc", "releases") libraryDependencies += "uk.gov.hmrc" %% "play-authorised-frontend" % "[INSERT-VERSION]"
It provides two traits from which user-aware controllers can be extended:
- Actions - This provides methods:
AuthenticatedBywhich allow different levels of authorisation, and provides the AuthContext object to your controller.
- DelegationAwareActions - This is used identically to Actions, but works in situations where the code allows delegated access. These actions require an
DelegationConnectorwith associated configuration.
The following connectors should be provided:
- The standard
AuthenticatedByActions requires a single
AuthConnectorto be provided.
- When using
DelegationAwareActions, both an
DelegationConnectorshould be provided.
It is vital to provide companion objects and all necessary configuration for the
###User and AuthContext
AuthContext class is the replacement of the
User class. The
User is a familiar remnant of previous incarnations of play-frontend and play-authorised-frontend.
AuthContext provides three fields:
user - This represents the logged in user; the person at the keyboard currently using the application
principal - This is the entity whose tax accounts are being used (person, organisation or holder of tax accounts).
attorney - This is an optional entity acting on behalf of the principal.
case class User(userId: String, userAuthority: Authority, nameFromGovernmentGateway: Option[String] decryptedToken: Option[String] actingAsAttorneyFor:Option[ActingAsAttorneyFor])
To help migrating, the mapping from
AuthContext fields are as follows:
User.nameFromGovernmentGateway == either
User.actingAsAttorneyFor - this is deprecated and has been removed in favour of the principal/attorney fields.
###Service Origin for Metrics for Securing Our Services
GovernmentGateway trait allows to set a
origin property which will be used by analytics tools to track the entire login journey.
By default this is the name of the application (
application.conf). You can set a value that is different from the application name globally in
application.conf with the
If you need to dynamically set the value per request, you need to override the
origin property in the
If you have a service that initiates the delegation flow, where a logged in user starts acting on behalf of another user, then you need to provide a controller extending
This provides two methods:
startDelegationAndRedirect(): This requires a
DelegationContextobject, containing the information you want to be made available in the target frontend. That is, the name of the principal, the name of the attorney, the account details which are to be made available in the target, and the link allowing the attorney to return to their home page (e.g. the agent dashboard). This method makes a service call to the Delegation microservice which stores the provided
DelegationContext, it then adds a delegation flag to the session and redirects to the target frontend address (i.e. that of the attorney's client).
endDelegation(): when the attorney wants to return to their origin, they click the callback link provided in the original
startDelegationAndRedirect()call. This should hit an endpoint which calls
endDelegation()method removes the current delegation context from the Delegation microservice, and removes the delegation flag from the session.
This code is open source software licensed under the Apache 2.0 License.