Page tree

Versions Compared


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


This guide addresses how to set up Argus to be an OAuth2 or OpenID Connect Identity Provider for your application.


To set up Argus to use an external OpenID provider for authentication into Argus, see External Identity Provider Integration Guide

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.

OpenID Connect Support

The Argus Identity Provider supports OpenID Connect, allowing integration with most standard OpenID-supporting clients.

By integrating using OpenID Connect, the 3rd party application can

  • authenticate users from Argus
  • get information about the current user from Argus (such as name, email, phone, user image)
  • fetch the users group membership
  • any other custom claims (which are supported by both Argus and the 3rd party client)

Required information about the client

Before configuring a new OAuth client in Argus, we need the following information about the client:

  • The main URI (landing page) to point to for the application
  • The redirect_uri (callback URI) to redirect back to
  • The IP(-ranges) the client will use when requesting the access token, which Argus users to protect against hijacked authorization tokens.

Configuring your Client


For a well-behaving OpenID Connect client, it should suffice to point the client to, as it should be able to pick up the configuration settings from

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
    1. The external application uses the authorization code to authenticate against Argus, using an form URL-encoded POST request:
      curl -XPOST -d
  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 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.


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.

Integration using OpenID Connect

Argus ID Provider supports OpenID clients. By using scope=openid  the client can request an OIDC flow.

The client can request additional scopes supported by Argus, to add more claims to the id token. Scopes should be listed as a space-delimited list of scope names:

  • Example plain text scopes: "openid groups profile"
  • Example URI-encoded scopes: "openid%20groups%20profile"

Valid scopes in Argus

  • groups - adds a claim "groups" which contains a JSON array of group shortnames:

    No Format
    "groups": [
  • groupstring  - adds a claim "groupstring" with a string-encoded JSON array of group shortnames (which is required by some OpenID clients)

    No Format
    "groupstring": "[\"mygroup1\",\"mygroup2\"]"
  • customer  - adds three claims with information about the domain and customer which the identified user is assigned to
    Note: this does not provide any information about permissions given to this user

    No Format
      "customer_id": 1,
      "domain_id": 1,
      "customer_shortname": "mycustomer",
      "customer_name": "My Customer"
  • email  - adds a claim "email"

    No Format
    "email": ""
  • profile  - adds claims for username, name and picture URI

    No Format
      "username": "myusername",
      "name": "My Users Name",
      "picture": ""
  • clientip  - adds a claim "client_ip" which contains the IP which this user session is bound to (which may be used to verify that requests are indeed coming from this IP). 
    Note: This is the IP as seen by Argus, so will not show a users private IP inside a NATed network or behind a proxy..

    No Format
    "client_ip": ""

Using scripted access to OAuth clients

To authenticate script users using OAuth, the OAuth client must support client credentials flow.

The script should first fetch an access token from the Argus OAuth Token endpoint

Code Block
curl -XPOST -H"Argus-API-Key: my/api/key" -d client_id=04d45a6b-05a1-4bed-8181-5c5d46d4f64e -d grant_type=client_credentials

Argus will respond with an access token:

Code Block

The script should then use this token as an Authorization:Bearer header towards the client application:

Code Block
curl -XPOST -H"Authorization:Bearer myUserName/ckEgvr23mT8PfPMPddVY7wYuuE6t6YmKLKr7tu3pV8ajvbGHzuJ9crvwoPFUBj9o" https://my.application/dosomething

The client application may invoke the Argus token endpoint to verify the token, or invoke any permitted Argus endpoint using this bearer token.

Code Block
curl -XGET -H"X-Forwarded-For:" -H"Authorization:Bearer myUserName/ckEgvr23mT8PfPMPddVY7wYuuE6t6YmKLKr7tu3pV8ajvbGHzuJ9crvwoPFUBj9o"

The client MUST forward the user agents origin IP using the X-Forwarded-For header, as Argus will verify that this IP corresponds with the IP used to initiate the session. 

Defining an OAuth2 / OpenID Connect Client

Defining 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" -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": [""],    # 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" -d
	"name": "A better name for my OAuth client"

Table of Contents