5 Cross-Cutting Requirements

Note that all of the requirements stipulated in this document and its references are reciprocal in that they also apply to components such as the API Management and Gateway services implemented by the security building block. For example the API Management and Gateway services deployed by this building block MUST also address their own intrusion prevention and detection needs referencing the solution requirements defined by this document.

The requirements stipulated in this document are themselves cross-cutting in that they apply to all building blocks and MUST be cross-referenced by the Building Block Definitions for each building block in the Cross-cutting requirements section.

Having these cross-cutting requirements defined centrally in this document and its references removes the issues of inconsistent, insufficient, costly and repetitive security implementation across all building blocks.

The cross-cutting requirements described in this document, its references and this section are an extension of the high level cross-cutting requirements defined in the architecture specification document and intended to specifically define the security requirements for the whole GovStack architecture in all layers.

This section describes the additional cross-cutting requirements that apply to the security building block as well as cross-cutting security requirements for ALL other building blocks. Note that cross-cutting requirements defined here use the same language (MUST or SHOULD) as specified in the architecture blueprint document (see Ref 1).

5.1 Privacy

Personal data MUST be kept private and never shared with any parties, except where specific authorization has been granted. This also applies to all acquired security components as they will often be logging personal data along with the transactional records. That logging data must also be considered private. Where CUI (Controlled Unclassified Information) is dealt with, the NIST 800-171 Rev 2 standard shall be applied (see Ref 3)

5.2 Security Requirements

Must refer reciprocally to this document and its references.

Security requirement is a condition over the phenomenon of the environment that we wish to make true by installing the system in order to mitigate risks. A requirement defining what level of security is expected from the system with respect to some type of threat or malicious attack.

5.5 Digital ID/Certificate Functional Requirements

5.6 Certificate Authority Functional Requirements

5.7 Credential Storage (i.e. LDAP) Functional Requirements

5.8 Time Sensitive Credential (i.e. OTP) Functional Requirements

5.9 Network Scanning and Vulnerability Management Requirements

5.10 Virus, Ransomware, Malware, Spam, Phishing Protection Requirements\

5.11 Denial of Service Attack Prevention Requirements

5.12 Applications Development Vulnerability Prevention Requirements

5.13 Infrastructure Vulnerability Remediation Requirements

5.14 Data Loss and Leakage Prevention Requirements

5.15 Data Encryption at Rest and In Transit Requirements

5.16 Social Network, Media and Engineering Threat Management Requirements

5.17 Cloud Security Posture Management Requirements

5.19 Vulnerability Management and Security Automation Requirements

5.20 Security Risk Profiling and Management Requirements

See the section of this document dealing with OSINT tools

5.21 Intrusion Prevention and Detection Requirements

5.22 Open Source Intelligence Platform (OSINT) Requirements

5.23 Fraud Prevention, Detection and Management Requirements

5.24 Security Incident Response and Management Requirements

5.25 Security Testing and Sandbox Requirements

5.26 Critical Digital Infrastructure Business Continuity Requirements

5.27 Data Structures

5.27.1 Resource Model

The resource model shows the relationship between data objects that are used by this Building Block. The following resource model depicts the basic elements of identity and access management (IAM) solutions required organized into domains:

5.27.2 Data Elements

The data elements provide detail for the resource model defined above. This section will list the core/required fields for each resource. Note that the data elements can be extended for a particular use case, but they must always contain at least the fields defined here. Information about data elements will include:

• Name

• Description

• Data Type

• Required/Optional flag

• Link to applicable standard(s)

• Notes

5.27.3 Example REST Authentication API

The following is a minimal example of how OpenIAM implements REST based authentication using its REST API:

(Note: The APIs will need to include appropriate request and response version numbers, for example, see https://docs.google.com/document/d/12b696fHlOAAHygFF5-XxUJkFyFjMIV99VDKZTXnnAkg/edit#heading=h.h9ypjkyetr1i)

URL

/idp/rest/api/v1/auth/public/login

Method

POST

Request Parameters

• login: user login (optional)

• password: user password (optional)

• postbackURL: redirectURL after success login (optional)

Headers

Content-Type:application/x-www-form-urlencoded

cURL Example

curl 'http://127.0.0.1:8080/idp/rest/api/auth/public/login' -X POST --data 'login=admin&password=pass123456'

Success Response Example

{
  "primaryKey": null,
  "status": 200,
  "errorList": null,
  "redirectURL": "/selfservice",
  "successToken": null,
  "successMessage": null,
  "contextValues": null,
  "possibleErrors": null,
  "passwordExpired": false,
  "userId": "3000",
  "unlockURL": null,
  "tokenInfo": {
    "authToken": "+Y9NkOrjOWn0BehKr6Cg1F7KcFIiY=",
    "timeToLiveSeconds": -1
  },
  "error": false
}

Error Response Example

{
  "primaryKey": null,
  "status": 500,
  "errorList": [
    {
      "i18nError": null,
      "error": "INVALID_LOGIN",
      "validationError": null,
      "params": null,
      "message": "Invalid Login and/or Password"
    }
  ],
  "redirectURL": null,
  "successToken": null,
  "successMessage": null,
  "contextValues": null,
  "possibleErrors": null,
  "passwordExpired": false,
  "userId": null,
  "unlockURL": null,
  "tokenInfo": null,
  "error": true
}

5.27.4 Example OAuth2 Authentication API

The following is a minimal example of how OpenIAM implements authentication with OAuth2 by requesting an OAuth2 token:

URL

/idp/oauth2/token

Method

POST

Request Parameters

• client_secret: Value of the client secret from OAuth client configuration page

• client_id: Value of the client ID from OAuth client configuration page

• grant_type: Type of grant flow

• username: Login of requester

• password: Password of requester

Headers

Content-Type:application/x-www-form-urlencoded

cURL Example

curl -v -XPOST --data 
'client_secret=AAAAA&client_id=BBBBB&grant_type=password&username=DDDD&password=EEEE' 'http://127.0.0.1:8080/idp/oauth2/token'
Success Response Example
{
"access_token": "ffj9Ub4lP-2_W4kXAXJ9MsleMxdDi9ALo0JqQw.3hV4driKa4IWXOSJ42PEQadFpN2FnpRruFLWD3",
"token_type": "Bearer",
"expires_in": 1320,
"refresh_token": "3nlth7DevrnjjpebATKkYCirs2aiy6L6SsBF_cpyxSXgVliwXC1rsCxRg99LCr7gHgYJ.A.VU"
}

Error Response Example

{
"error": "unauthorized_client",
"error_description": "Missing required parameter: client_id or client application is not registered"
}

5.27.5 Example OAuth2 Token Renewal API

The following is a minimal example of how OpenIAM implements authentication token renewal:

URL

/idp/rest/api/auth/renewToken

Method

GET

Headers

• Authorization: with oAuth token in format 'Bearer: <token>'

• Cookie: with current valid authentication token in format 'OPENIAM_AUTH_TOKEN=<token>'

cURL Example

// Scurl -XGET -v -H 'Authorization: Bearer ssssss' -H 'Cookie: OPENIAM_AUTH_TOKEN=asdasdas' 'http://127.0.0.1:8080/idp/rest/api/auth/renewToken'

Success Response Example

{
"authToken": "asdas+asd/YagqkcJEql+asd=",
"timeToLiveSeconds": -1
}

Error Response Example

5.27.6 Example OAuth2 Authorization API

The following is a minimal example of how OpenIAM implements authorization using OAuth2:

URL

{server_url}/idp/oauth2/token/authorize

Replace {server_url} with the name of the server.

Method

GET

Parameters

• response_type: codetoken

• client_id: webconsole/Access Control/Authentication Providers/*needed provider* edit/ Client ID field

• redirect_uri: webconsole/Access Control/Authentication Providers/*needed provider* / Redirect Url. Use 'Space' or 'Enter' to separate values field.

cURL Example

curl

'http://dev1.openiamdemo.com:8080/idp/oauth2/authorize?response_type=code&client_id=EF4128DCC0D24ED3BAC17FC918FDDBF5&redirect_uri=http://dev1.openiamdemo.com:8080/oauthhandler'

or, just:

curl

'http://dev1.openiamdemo.com:8080/idp/oauth2/authorize?response_type=code&client_id=EF4128DCC0D24ED3BAC17FC918FDDBF5&redirect_uri=http://dev1.openiamdemo.com:8080/oauthhandler'

Success Response Example

redirect to redirect_uri?code=code

Error Response Example

redirect to redirect_uri with error

5.27.7 Example OAuth2 Authorization Implicit Grant Flow API

The following is a minimal example of how OpenIAM implements an implicit grant flow API style of authentication:

URL

{server_url}/idp/oauth2/token/authorize

Replace {server_url} with the name of the server.

Method

GET

Parameters

• response_type: token

• client_id: webconsole/Access Control/Authentification Providers/*needed provider* edit/ Client ID field

• redirect_uri: webconsole/Access Control/Authentification Providers/*needed provider* / Redirect Url. Use 'Space' or 'Enter' to separate values field.

cURL Example

curl -v XGET 'http://dev1.openiamdemo.com:8080/idp/oauth2/authorize?response_type=token&client_id=EF4128DCC0D24ED3BAC17FC918FDDBF5&redirect_uri=http://dev1.openiamdemo.com:8080/oauthhandler'

or, just:

curl 'http://dev1.openiamdemo.com:8080/idp/oauth2/authorize?response_type=token&client_id=EF4128DCC0D24ED3BAC17FC918FDDBF5&redirect_uri=http://dev1.openiamdemo.com:8080/oauthhandler'

Success Response Example

redirect to redirect_uri?code=access_token=Pcej-9OdU_wshAjTn76MP-Cj5OgY_sfdYrt&expires_in=60000&token_type=Bearer

Error Response Example

redirect to redirect_uri with error

5.27.8 Example Get OAuth2 Token Information API

The following is a minimal example of how OpenIAM implements a get operation for token information:

URL

{server_url}/idp/oauth2/token/info

Replace {server_url} with the name of the server.

Method

GET

Parameters

token: token should be created via Create token.

cURL Example

curl -v XGET

'http://dev1.openiamdemo.com:8080/idp/oauth2/token/info?token=rdSOyor6hqJ2CrQ5QrpeXgX.ItgVEx1.nskN'

or, just:

curl

'http://dev1.openiamdemo.com:8080/idp/oauth2/token/info?token=rdSOyor6hqJ2CrQ5QrpeXgX.ItgVEx1.nskN'

Success Response Example

{
"expired": false,
"client_id": "92BF26DD50D748668730F7639C4A0D3D",
"user_id": "3000",
"access_token": "Lf_Sc-YeKHB8rsGfiGcLMKJOxbTGmpbdYs5wK3i7ZhINrjJlTOHEuV-phwJ1wE7.MjWqDcx8Lpri",
"expires_in": 1709,
"expires_on": 1531332707193,
"scopes": [
{
"scopeId": "c42a190a6488010b01648810b83a005a",
"name": "dev1 - /idp/oauth2/token/info"

},
{
"scopeId": "c42a190a6488010b01648810bdfd0096",
"name": "dev1 - /idp/rest/api/*"
},
{
"scopeId": "c42a190a6488010b01648810be2a0098",
"name": "dev1 - /webconsole/rest/api/*"
},
{
"scopeId": "c42a190a6488010b01648810be6d009b",
"name": "dev1 - /selfservice/rest/api/*"
},
{
"scopeId": "c42a190a6488010b01648810be96009d",
"name": "dev1 - /selfservice-ext/rest/api/*"
},
{
"scopeId": "c42a190a6488010b01648810bebf009f",
"name": "dev1 - /webconsole-idm/rest/api/*"
}
]
}

Error response example

// Some code{"code":401,"error":"invalid_token","error_description":"Authorization token is expired"}

5.27.9 Example Create OAuth2 Token API

The following is a minimal example of how OpenIAM would create an OAuth2 token using authorization grant flow style:

URL

{server_url}/idp/oauth2/token

Replace {server_url} with the name of the server.

Method

POST

Parameters

• client_secret: webconsole/Access Control/Authentification Providers/*needed provider* edit/ Client Secret field

• client_id: webconsole/Access Control/Authentification Providers/*needed provider* edit/ Client ID field

• grant_type: authorization_code

• redirect_uri: webconsole/Access Control/Authentification Providers/*needed provider* / Redirect Url. Use 'Space' or 'Enter' to separate values field

• code: code should be generated with Authorization code grant flow request.

Headers

Content-Type: application/x-www-form-urlencoded

cURL Example

curl -v -XPOST --data 'client_secret=client_secret&client_id=client_id&grant_type=authorization_code&redirect_uri=redirect_uri&code=code' 'http://dev1.openiamdemo.com:8080/idp/oauth2/token'

Success Response Example

{
"access_token": "MjwOxreF7e-NW_NBA6UNuB9d_4IcohdK2bUSxqZ_BxDlCG7uD.ZstmoKwvuWq1hL49pClk3dlo",
"token_type": "Bearer",
"expires_in": 1800
}

Error Response Example

{
"error": "invalid_request",
"error_description": "Code parameter is expired"
}

{
"error": "invalid_request",
"error_description": "Redirect URL does not mach to initial one."
}

5.27.10 Example Revoke OAuth2 Token API

The following is a minimal example of how OpenIAM implements OAuth2 token revocation:

URL

{server_url}/idp/oauth2/token/revoke

Replace {server_url} with the name of the server.

Method

POST

Headers

Content-Type=application/x-www-form-urlencoded

Parameters

token: token should be created via Create token.

cURL Example

curl -v XPOST --data 'token=token' 'http://dev1.openiamdemo.com:8080/idp/oauth2/revoke'

Success Response Example

{
"status": "SUCCESS",
"errorCode": null,
"errorText": null,
"fieldMappings": null,
"stacktraceText": null,
"responseValue": null,
"errorTokenList": null,
"failure": false,
"success": true
}

Error Response Example

{"code":403,"error":"insufficient_scope","error_description":"The request requires higher privileges than provided by the access token","scope":"1531291154553_/idp/oauth2/revoke"}

**5.**27.11 Example Validate OAuth2 Token API

The following is a minimal example of how OpenIAM implmenents OAuth2 token validation:

URL

{server_url}/idp/oauth2/token/validate

Replace {server_url} with the name of the server.

Method

GET

Parameters

token: token should be created via Create token.

cURL Example

curl -v XPOST --data 'refreesh_token=refreesh_token' 'http://dev1.openiamdemo.com:8080/idp/oauth2/token/refresh'

Success Response Example

{
"access_token": "j4I6p0vDxZKduJXlipXZq5LNQqY1aJWvtYp812.k6246Sn2FY3rpyos..qJtScD8.wjytm1idsnopHmb.u",
"token_type": "Bearer",
"expires_in": 60,
"refresh_token": "0q1V8ZJaayxV5qcD4JtwF5.LyQOPMaZY.cNsIuZAYQ-TXGqrZDpy6AEOhc58dwEjgHDN2Bx_J.XkVTZ"
}

Error response example

{
"timestamp": 1531449532875,
"status": 400,
"error": "Bad Request",
"exception": "org.springframework.web.bind.MissingServletRequestParameterException",
"message": "Required String parameter 'refresh_token' is not present",
"path": "/idp/oauth2/token/refresh"
}

5.27.13 Example User Information from OAuth2 Token API

The following is a minimal example of how user information can be obtained from OpenIAM using an OAuth2 token:

URL

{server_url}/idp/oauth2/userinfo

Replace {server_url} with the name of the server.

Method

GET

Parameters

token: token should be created via Create token.

cURL Example

curl -v XGET 'http://dev1.openiamdemo.com:8080/idp/oauth2/userinfo?token=rdSOyor6hqJ2CrQ5QrpeXgX.ItgVEx1.nskN'

or, just:

curl 'http://dev1.openiamdemo.com:8080/idp/oauth2/userinfo?token=rdSOyor6hqJ2CrQ5QrpeXgX.ItgVEx1.nskN'

Success Response Example

{
"sub": "3000"
}

Error Response Example

{"code":401,"error":"invalid_request","error_description":"Authorization token is not found"}
{"code":403,"error":"insufficient_scope","error_description":"The request requires higher privileges than provided by the access token","scope":"1531291154428_/idp/oauth2/userinfo"}

4.27.14 Example API for Defining Resources, Roles, Access and Provisioning

The most comprehensive API available for this is delivered by OpenIAM. Unfortunately this API is currently delivered in SOAP. The purpose of this API is to provide 3rd parties the ability to create resources, roles and access within the IAM system. There are multiple options to get this done including batch upload and configuration using the administrative user interface. This would need to be addressed at implementation time using the most practical means. There does not seem to be a current use case for the BB’s to create these types of resources on the fly using the IAM API. The API definitions can be found here: https://docs.openiam.com/docs-5.1.14/html/docs.htm#API/SOAP/SOAP.htm%3FTocPath%3DAPI%2520Guide%7CPart%2520II%253A%2520SOAP%2520API%2520integration%2520services%7C_____0