Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Tip

Please read the General Integration Guide to learn the general concepts and common data structures used throughout the Argus API.



Detailed API documentation

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

OAuth2 Integration

Understanding Argus OAuth2 Clients

Using Argus as an OAuth2 Identity Provider, an external application may be defined as an OAuth2 client.

This allows

  • allowing a user to authorize the external client to access Argus on behalf of the user.
  • allow the external client to authenticate the user which is logged in using Argus credentials

A user accessing the external client, will be redirected to the Argus portal for authorization.
If successfully authorized, Argus will redirect the user back to the external client, with a authorization code. The external client can use this authorization code to aquire an Argus session on behalf of the user.

Argus OAuth2 Access Control

  • An Argus OAuth2 Client is bound to a required role, which the user must have granted in order to be authorized to use the client.
  • The Client may optionally be bound to a specific customer, in which case the user must be granted the required role for that particular customer, before being granted access. 
  • Listing OAuth2 Clients from Argus, a user will only be presented the clients which he/she is authorized to access.

Argus OAuth2 Permission Scope

  • An OAuth2 client being authorized to access Argus, is provided with a new session, bound to the authorizing user. This session is always constrained by the credentials of that user, and API invocations using this session will impersonate the user.
  • In addition, the client is defined with a Permission Scope, which is an outer constraint on the credentials which the clients session may be granted.
  • The client session is thus constrained to the intersection of the Permission Scope, and the permissions of the authorizing user.

Argus OAuth2 Client IP Restriction

  • An additional security feature of the Argus OAuth2 IdP, the OAuth2 Client is administratively specified with a client IP range, from which Argus expects the client to originate from. 
  • This security feature allows defining constraints well-known clients, which are expected to originate from a known infrastructure, so they cannot originate from other IPs.

Creating an OAuth2 Client

Tip
Creating an OAuth2 Client is generally done by an administrator. 


To define a new OAuth2 Client:

No Format
curl -XPOST -H"Argus-API-Key: my/api/key" https://api.mnemonic.no/authentication/v1/oauth/client -d
{
	"shortName": "myclient",
	"name": "My OAuth Client",
	"description": "This is the description of the client",
	"customer": "mycustomer",
	"mainURI": "https://my.application",
	"redirectURI": "https://my.application/oauth/callback"
	"requiredFunction":"myAccessFunction",  # define a special access function, which is required for the user to get access
	"permissionScope":"DATASTORE-VIEWER",   # allow the client to access the datastore, read only
	"clientIPRange": ["192.168.1.0/24"],    # I know where this application runs!
	"clientSecret": "mySecretPassword"      # Share this secret with the OAuth2 client, to allow it to contact the Token endpoint
  }
}


The returning OAuth2 Client object contains the client ID, which should be used in the OAuth2 protocol exchange:

No Format
{
  "id": "021269c5-04c3-4399-a206-32659c489803", ...
}


Updating an OAuth2 Client

The update endpoint allows changing the properties of the agent afterwards.
See the Swagger API documentation for details.

No Format
curl -XPUT -H"Argus-API-Key: my/api/key" https://api.mnemonic.no/authentication/v1/oauth/client/myclient -d
{
	"name": "A better name for my OAuth client"
  }
}


Configuring your OAuth2 Client

OAuth2 Client Authorization

  1. The user agent (browser) access the application, on e.g. https://my.application, and is redirected to the Argus OAuth authorization page
  2. If not logged into Argus, the user is redirected to the Argus Login page, and then back to the OAuth authorization page 
  3. If the current user is permitted to access the specified client, Argus issues an authorization code, and redirects the user back to the redirectURI
    https://my.application/oauth/callback?code=b11f9f83-899b-42cb-a131-790d5a40247
    1. The external application uses the authorization code to authenticate against Argus, using an form URL-encoded POST request:
      curl -XPOST https://api.mnemonic.no/authentication/v1/oauth/token -d
      client_id=021269c5-04c3-4399-a206-32659c489803&client_secret=mySecretPassword&grant_type=authorization_code&code=b11f9f83-899b-42cb-a131-790d5a40247&redirect_uri=https://my.application/oauth/callback
  4. Argus returns a Bearer token to the client, which is a valid Argus user session, with a short lifetime.
    To use this token, the OAuth client muse must use an Authorization: Bearer-header:
    Authorization: Bearer someuser/Pheifoo1dainoofa1uede5booxe0ahQu

The OAuth client application can now use the Bearer header to issue API operations on behalf of the authorizing user.

Note

The OAuth session must be refreshed within the refresh timeout. If at the time of refresh, the authorizing user is logged out, the OAuth session will be rejected.

The OAuth session is constrained to the permissions of the authorizing user, in addition to the constraints imposed by configuration. The session will have the permissions which constitutes the intersection of the users permissions, and the constraints configured on the client.


Table of Contents