Authentication and Cross-BB Authorization

In order to enable the delivery of GovStack use cases, a mechanism must be defined that provides the appropriate level of access to the various building blocks by different users and organizations. This includes defining information sharing across service or organizational boundaries, enforcing appropriate roles and permissions for users, allowing user session information to be passed between building blocks, and enforcing secure access between Building Blocks (either co-located within a service, or across applications/organizations using an Information Mediator).

This document outlines key Authentication and Authorization services that will be offered by a common Authorization Service and outlines the key interactions between the Authorization Service, Identity Building Block, Information Mediator, and other Building Blocks.

Key Requirements

• The Identity Building Block is responsible for handling Foundational Identity.

• The Authorization Service should offer a mechanism for authentication (managing sign-on, SSO, etc), as well as authorization (mapping functional identities to a particular user, allowing roles and permissions to be assigned to a user using IAM/RBAC, and generating tokens that can be used in web requests between services).

  • Authentication concerns can often be centralized (SSO services). Further detail on authentication is defined in <this document>

  • Government-wide implementations will require multiple Authorization services to be maintained by each domain or ministry/government department, or even specific application/service. The same tools, protocols, and communication mechanisms should be used across domains.

  • Authentication and Authorization (IAM/Roles/Permissions/Policies) should be implemented using well-defined standards like OpenID Connect (OIDC).

  • Authorization services may be specific to individual applications or services as well, again using common The authorization services should be implemented as standalone Services using common tools and well-established protocols and policy languages, such as Rego or Cedar.

• After user login (authentication) and retrieval of roles/permissions/policies for that user (authorization)

  • The Application is responsible for managing any outbound calls based on the roles/permissions for that user - whether to internal BBs or cross-organizational requests through IM.

  • The Application will manage the API keys/credentials needed to access any local BB APIs that it calls

  • We will not pass user/session information when making API calls to local BBs

  • We will not pass JWT tokens or roles when making API calls through Information Mediator

• JWT/tokens need to be exchanged between different UIs/applications - If we need to pass control over to another app to fill in some information (giving consent, etc) - use OIDC

• The Information Mediator is used to facilitate communication between different organizations. The authorization and level of access is defined at the organization level, not the user level (ie. this particular organization has permission to access this set of data)

  • The security server will hold/manage credentials and API keys that are needed for accessing remote services

  • An organization can also allow access to an individual user based on a foundational ID

• IM is needed when going outside of a local network (ie. across the internet)

For accessing an existing DPG:

• Set up an account/set of credentials in the other DPG/application that allows access to the APIs

• The authorization services (either within the application or separate functionality) will hold the login credentials in some type of secret storage (.env file or similar mechanism)

• When calling an API in the DPG, the Application should first call the DPG login API (there must be an API exposed for login) and then hold the token that is needed for API calls

• The Application will pass the appropriate token on subsequent API calls to the DPG

Definitions

Application: One or more Building Blocks that may be combined with a UI and/or internal services which implement some business logic to provide a set of related services.

Authentication: This is the process of validating a set of functional user credentials which will allow them to access a system. Largely synonymous with ‘Login’

Authorization: A mechanism to determine if a user has permissions to perform a particular action, and/or what roles/permission a particular user has within a system.

Foundational Identity: a unique identifier for an entity that corresponds with a national identification system

Functional Identity: a login or user account that is associated with a particular application or set of services

Information Mediator: Connects applications across the internet, allowing services that are owned by different organizations to share data securely and using agreed-upon rules

Organization: An entity that maintains one or more applications or services that may be consumed by other organizations

Service: An API or endpoint provided by a Building Block or internal microservice of the Application

Session: a set of information (or token) that provides context to a particular user interaction with an application (ie. keeping track of a logged-in user and what they have permission to do while they are logged in for a particular period of time)

Use Case/User Journey: A system involving one or more UX components that allows a user to access multiple services which may be co-located or require the use of an information mediator to access a set of services/applications.

User: An individual that is accessing a particular application or set of services

Scenarios

Authentication and Authorization flow

Notes:

• The Mapping of foundational ID to functional ID for this application can happen in ID BB or in auth services.

• Application is then responsible for managing control and access for this user, based on their permission bundle

Co-located services

1. An application will use an authorization Building Block for user login and role/permission management. The application will ensure that any outbound requests are filtered by that user’s role. A token does not need to be passed to Building Blocks when calling a service endpoint.

2. If the application needs to call another application which will present a UI, then a token should be passed to the second application containing the user information.

Cross-organization services using Information Mediator

1. Data is shared between services/applications provided by different organizations, requiring an Information Mediator

2. The data sharing that is allowed between organizations is defined through the information mediator. The application is responsible for doing an organization authorization and understanding what roles this user has for interactions with the outside organization.

Key Questions

• How do we onboard new applications/use cases/services into a GovStack implementation?

• Do we need to have the ability for a DPG/BB to call back to the application?

  • If BBs need to access services/information from other BBs? Then they would need to store the credentials for accessing the other APIs

  • For connections using IM, this could be managed by PubSub or Security server - credentials provided when you subscribe to a room/channel

• We need to define the scope and functionality of the Authorization Services, along with how we manage IAM and Roles (OIDC IAM?)

• Do we need to document how to configure organizational roles/access permissions in the Information Mediator as well as things like storage of API keys? How do we define what information a particular organization (or user) has access to within another organization?

• Do we need to handle commercial registries (individuals acting on behalf of a company)? 

To Do:

• Provide a diagram of an authorization service configuration

  • Authentication → Return functional ID (after Foundational ID lookup) → Query policy engine/authorization services → Return policies/authorizations (OPA/PDP?) → Application renders appropriate information/screens/actions for that user

• Document protocols/policy languages like Rego, Cedar, and OPA/PDP and specific tools that could be used

• Document the mechanisms for ID Mapping - how is a user onboarded to an application or set of services and how is a functional ID/token generated.

  • The process should be similar to the PSUT system implemented by MOSIP, but we should find more generic terminology

• Document the authorization process for existing DPGs clearly in the cross-cutting and security specs.

• Document how services can access other services through IM

• Document the flow for UI handoff to another UI

• Document Example OIDC Onboarding process for a BB

• Document Example IM Onboarding process for an organization

Notes:

Original diagram for above sequence (along with notes) is here:

Open

1. note the police user (we don’t know and don’t care how the police department makes their officers “log in” to their various web apps). how they do IAM at the police department is totally up to the police department. this isn’t an IM concern.

2. note that the request in ORANGE LINES between that client and server is not via the IM.

3. note the way the request is phrased differently when the POLICE APP asks the TAX SERVICE.

4. note that the request in RED LINES doesn’t know about the police user, and it also doesn’t know that the tax service API actually needs an apiToken. it’s oblivious to all that. it’s just got an x-road-header and allowed to take place because there is a contract (established on the IM) that allows the POLICE APP to access some specific part of the TAX SERVICE.

5. note that before the request actually reaches the SALARY INFO APPLICATION it has an apiToken added to it.

6. note the phrasing of the response of the TAX SERVICE.