Configuring a Resource Server

You can define settings for encrypting access tokens by adding a resource server in Identity Server. You can add a resource server based on the encryption requirement of each OAuth resource server. A resource server validates and accepts tokens sent by client applications and grant access to resources.

You can select any resource server as the default resource server. Then the tokens are issued and encrypted using the default resource server keys. If you do not select any resource server as the default resource server, then Identity Server is considered as the default resource server.

You can also modify and delete configured resource servers. Configuring a resource server consists of the following actions:

Adding a Resource Server

Adding a resource server in Access Manager (Identity Server) is required only for specifying any of the following access token encryption mechanism for a specific OAuth resource server:

Encrypt using Access Manager key (default)
Encrypt using resource server key
No encryption

Access and ID tokens contains scopes (user’s claims) in the form of user attributes or permissions for the clients to use the protected resource. You can configure scopes for each resource server.

When a client application requests for a token with specific scopes and the user provides the consent, Identity Server (authorization server) checks if the scope is available in any of the added resource servers. If available, the scope is added to the access token irrespective of the name of the resource server specified in the request.

Scenario 1

An administrator adds resource servers RS1 and RS2 based on the access token encryption requirement of the corresponding OAuth resource servers.

The administrator configures RS1 to use Access Manager key for encrypting access token and configures RS2 to use the resource server's key. In addition, the administrator defines the scope, Scope1 for resource server RS1 and the scope, Scope2 for resource server RS2.

Resource Server	Encryption mechanism	Scopes
RS1	Encrypt using Access Manager key	Scope1
RS2	Encrypt using resource server key	Scope2

When the client application sends a token request with scope parameter as Scope1 and resourceServer parameter as RS2, Identity Server adds Scope1 to the token with the encryption mechanism specified in RS2.

Request		Response
Parameter	Value	Scope added to token	Token encryption mechanism
resourceServer	RS2	Scope1	Encrypted using resource server, RS2 key
scope	Scope1	Scope1	Encrypted using resource server, RS2 key

Scenario 2

The administrator selects RS1 as the default resource server, and configures both RS1 and RS2 to use the resource server's key to encrypt access token. The resourceServer parameter is not defined.

Resource Server	Encryption mechanism	Scopes
RS1 (default)	Encrypt using resource server key	Scope1
RS2	Encrypt using resource server key	Scope2

When the client application sends a token request, Identity Server adds Scope1 to the token with the encryption mechanism specified in RS1.

Request		Response
Parameter	Value	Scope added to token	Token encryption mechanism
scope	Scope1	Scope1	Encrypted using resource server, RS1 key

IMPORTANT:Be careful if you change the default resource sever because certain requests can fail.

For example, if you change the default resource server from RS1 to RS2, the token will be issued and encrypted using RS2 keys. Then, if a client application sends a token encrypted by RS1 keys, the token request will fail because RS1 is not the default resource server.

If you delete the default resource server, and Identity Provider is available, it becomes the default resource server. If Identity Provider is not available, the tokens are encrypted using the Access Manager keys.

When Identity Provider is the default resource server, you cannot delete it or modify the name. You can set only one resource server as the default one at a time.

Scenario 3

The administrator selects RS2 as the default resource server, and configures both RS1 and RS2 to use the resource server's key to encrypt access token.

Resource Server	Encryption mechanism	Scopes
RS1	Encrypt using resource server key	Scope1
RS2 (default)	Encrypt using resource server key	Scope2

Now, when the client application sends a token request with scope parameter as Scope1 and resourceServer parameter as RS1, Identity Server adds Scope1 to the token with the encryption mechanism specified in RS1. When defined, the resourceServer parameter is given priority over the default resource server setting.

Request		Response
Parameter	Value	Scope added to token	Token encryption mechanism
resourceServer	RS1	Scope1	Encrypted using resource server, RS1 key
scope	Scope1	Scope1	Encrypted using resource server, RS1 key

Perform the following steps to add a resource server in Identity Server:

Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Servers > New.
Specify a name for the resource server.
(Optional) Select Set it as the default Resource Server. When you enable this option, tokens are issued and encrypted using the default resource server keys
Select the appropriate encryption method for encrypting access token. For more information about encrypting an access token, see Encrypting Access Token.
- Do not encrypt: Select this option if you do not require encryption of Access token.
- Encrypt using Access Manager Key: This is the default option. If you select this option, the token is encrypted and validated by using Access Manager Keys.
- Encrypt using Resource Server Key: This option is used for encrypting a token by using encryption algorithm and keys that the resource server can use for decrypting the token.
(Conditional) If you select Encrypt using Resource Server Key, specify the following details:

For information about fields, see Encrypting the Token with the Resource server Key.
- Resource Server Encryption Keys: Specify the resource server’s JWKS. You can also specify a valid URL where the resource server keys are defined.
- Key Encryption Algorithm: Specify the algorithm that should be used for encrypting the key of the encrypted token by using the resource server’s public key.
  
  Ensure that this algorithm can be used by one of the public keys in the resource server’s JWKS or the URL.
  
  NOTE:If the specified key encryption algorithm does not match with the value of the algorithm in Resource Server Encryption Keys, Access Manager fails to send the token.
- Token Encryption Algorithm: Specify an algorithm available in the resource server’s JWKS for generating random symmetric key to encrypt the access token.
Following is an example of JSON Web Key set that can be used when Key Encryption Algorithm is selected as A128KW and the Token Encryption Algorithm is selected as A128CBC-HS256(Default):
```
{
    "keys": [
        {
            "kty": "oct",
            "use": "enc",
            "kid": "i8X0RShbVxrBEG1-ests_Zx_PE7XYvc3iBTIaTAS_5A",
            "k": "Vlbwxl5hbCOLMwupPc2hDw",
            "alg": "A128KW"
        }
    ]
}
```
NOTE:You cannot configure resource server with JWKS containing kid value between 0-10 as it is used by Access Manager keys.
Click Next.

Continue with Defining Scopes for a Resource Server.

IMPORTANT:Before deleting a resource server, ensure that it is not used in any OAuth token inject policy.

Restricting the Number of Requests

You can restrict the number of users accessing a service by updating the tomcat.conf file.

Open Identity Server’s tomcat.conf and add the following parameter:

JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.oauth.threshold.maxrequestsallowed=<number of requests>"

For example, JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.oauth.threshold.maxrequestsallowed=10". It will not allow more than 10 requests per second.

For information about how to open and modify a file, see Modifying Configurations.