Oauth2 authentication routes and API integration accounts now available

[saltaverde]

Yesterday we deployed Oauth2 authentication flows to the test sandbox for NERIS available at the /v1/token endpoint. These flows issue two different types of JWTs: Cognito-signed and NERIS-signed. The NERIS API recognizes both signatures as valid for access tokens.

The password flow generates Cognito-signed JWTs and supports MFA via email. Upon successful authentication, the server returns an access token and refresh token. The refresh token can be used to generate fresh access tokens until it expires (currently 90 minutes). As Cognito opts not to issue new refresh tokens when tokens are refreshed, the initial password flow must be re-executed in order to generate a new refresh token. These Cognito-signed tokens are considered user account tokens as they are associated with a user in the Cognito user pool which represents a person.

The client_credentials flow generates NERIS-signed JWTs. No MFA is required or supported for this flow as client IDs and client secrets can only be created by user accounts (behind MFA). Endpoints under /account provide the functionality to generate what we term integration accounts--accounts not tied to a specific individual but rather an entity (vendor, department, or other) and are designed specifically for programmatic access. The client_credentials flow issues an access token and refresh token. Unlike the user account tokens, these refresh tokens can be used to generate new access AND refresh tokens, so in theory the tokens could be refreshed indefinitely via the refresh_token flow.

Concurrently, we are releasing NERIS API Client 1.2.0 which supports the new Oauth2 flows. You are welcome to take a look at how we implemented interacting with the /v1/token endpoint in that client.

The NERIS API is still compatible with any valid Cognito-generated JWT for the correct user pool, so tokens created via Cognito IntiateAuth will still work.

Vendors
In order to begin creating integration accounts (integrations) so that you can begin submitting on behalf of a department in the test sandbox, please submit a request to the helpdesk for a vendor entity. Your company will be assigned an entity in NERIS beginning with VN that you will be able to create integrations for.

Once you have been assigned a vendor entity and created an integration, you can submit a request to enroll a department in the test sandbox and begin testing submitting on behalf of one or more departments (depending on how many enrollments you request) using the client_credentials auth flow. Documentation for creating integrations can be found in the NERIS API documentation. IMPORTANT: Integrations can only be created by user accounts (which are secured with MFA in production), so you will need to authenticate as a user to make requests to POST /account/integration/{entity_id}

We are working on adding all of this integration management into the UI so this process will be more frictionless. Thanks for your patience as we get that implemented.

[bentleycook]

Update: I found the correct helpdesk: https://neris.atlassian.net/servicedesk/customer/portal/3/group/6/create/10027

---

It looks like the links to the helpdesk are no longer valid:

Is there a new place one can raise a request for vendor access?