Page tree

Versions Compared

Key

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

Overview

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

Tip

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)

Configuring your Client

Tip

For a well-behaving OpenID Connect client, it should suffice to point the client to https://portal.mnemonic.no, as it should be able to pick up the configuration settings from
https://portal.mnemonic.no/.well-known/openid-configuration

OAuth2 Client Authorization

Image Modified

  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 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.


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": [
        "mygroup1",
        "mygroup2"
      ]
  • 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": "user@domain.com"
  • profile  - adds claims for username, name and picture URI

    No Format
      "username": "myusername",
      "name": "My Users Name",
      "picture": "https://api.mnemonic.no/users/v2/user/1000/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": "94.127.56.1"

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" https://api.mnemonic.no/authentication/v1/oauth/token -d client_id=04d45a6b-05a1-4bed-8181-5c5d46d4f64e -d grant_type=client_credentials

Argus will respond with an access token:

Code Block
{"access_token":"myUserName/ckEgvr23mT8PfPMPddVY7wYuuE6t6YmKLKr7tu3pV8ajvbGHzuJ9crvwoPFUBj9o","id_token":null,"refresh_token":null,"token_type":"Bearer","expires_in":300}


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: 94.127.56.1" -H"Authorization:Bearer myUserName/ckEgvr23mT8PfPMPddVY7wYuuE6t6YmKLKr7tu3pV8ajvbGHzuJ9crvwoPFUBj9o" https://api.mnemonic.no/authentication/v1/oauth/userinfo
Note

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

Tip
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" 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"
  }
}



Table of Contents