1.6.5. Authorization Policies#

Starting with LinOTP 2.5 Authorization policies are supported. This means you can define, which users from which realm are allowed to login to which client. Therefore LinOTP grabs the HTTP client, that is doing the HTTP request. In case of using a RADIUS-Server, it will always be the IP address of the RADIUS server, that talks to the LinOTP server. Therefore the RADIUS server can impersonate the client by sending an additional URL attribute “client” containing the RADIUS clients IP address to the LinOTP server.

In the system config you may define “Override Authentication client” which is a comma separated list of IP addresses, that are allowed to send other client IPs.

Authorization#

To define an authorization policy you need to do the following:

  • Policy name: This is the unique name of the policy.

  • Scope: This needs to be authorization.

  • Action: This needs to be authorize. There are no other actions at the moment.

  • Realm: This is a list of realms or ‘*’ for all realms. A user must be member of this realm to be authorized to authenticate to the defined clients.

  • User: This is a list of users or resolvers. See Users in policies for more details.

  • Client: This is a list of IP addresses or IP subnets.

Such a policy will define, that the users from this realm are allowed to login on the specified client. If a policy for users is specified, these users are not allowed to login at other clients than defined in this policy.

Also, other users, that are not mentioned in this policy, are not allowed to login to the clients in this policy.

Note

If a policy for a client 192.168.20.10 and a UserA in Realm1 is specified, then the UserA and the UserB in Realm1 will not be allowed to login to client 192.168.20.11.

Token Types#

Using this policy you may define, that a user will only be allowed to login with the correct token type. You may add several token types to a policy, so that the user may choose between two or three token types.

  • Policy name: This is a unique name of the policy.

  • Scope: You need to set this to authorization.

  • Realm: Enter the name of the realm.

  • Action: Use the format tokentype=HMAC TOTP PW. (may contain ‘*’).

  • User: This is a list of users or resolvers. See Users in policies for more details.

  • Client: This is a list of IP addresses or IP subnets.

Note

The entered password gets validated, i.e. if the user enters a correct OTP PIN and OTP value this is validated and the counter is increased, so that those values can not be used to login to another client.

If the user enters valid OTP values, the Fail Counter is not increased, even if he is not allowed to login with this token type on this very client.

Note

The user specified in this policy may only login at the specified client with the specified token. I.e. this specified user may login with another token type at another client. This also means that a user not specified in this policy can also login to this specified client with another token type.

So if you want make sure, that at a specified client only one token type is allowed to login, you must make sure that all users are either contained in this policy or that users, who should not be allowed to login at that client are defined in an authorize policy.

Serials#

In some cases restricting access due to the token type may not be enough.

Imagine users having a YubiKey enrolled in OATH mode and an event-based Google Authenticator. Both tokens will be known to LinOTP as of the type “HMAC”.

But you might want to distinguish between these two tokens, since one is a hardware which which might be seen as more secure than the software token.

For this you can use the following policy:

  • Policy name: The unique name of the policy.

  • Scope: You need to set this to authorization.

  • Realm: Enter the name of the realm.

  • Action: Use the format serial=^UBOM.*.

  • User: This is a list of users or resolvers. See Users in policies for more details.

  • Client: This is a list of IP addresses or IP subnets.

The string ^UBOM.* can be a regular expression [1]. This regular expression will match on all YubiKeys in OATH mode. You could also match on a range of specific serial numbers.

Note

As the comma is used as separator for the actions, your regular expression can not contain a comma.

Footnotes

Setting Realms#

The setrealm policy can be used to define a fixed realm for an authenticating client. When this policy is triggered the initial log-in realm of the authenticating user is overwritten to the target realm, that is defined in the policy action as parameter.

  • Policy name: This is a unique name of the policy.

  • Scope: You need to set this to authorization.

  • Realm: Specify the login realm or login realms as a comma separated list for which this policy should be valid or the wildcard ‘*’, if this should match for any login realm.

  • Action: Use the format setrealm=target_realm to define, what should be the new realm of the authenticating user.

  • User: This is a list of users. You can not define resolvers here, since the user might not be member of the login realm! See Users in policies for more details.

  • Client: This is a list of IP addresses or IP subnets.

Note

Take care: if the user is logging in like ‘user@login_realm’ the LinOTP configuration System Config ‘Split At Sign’ must be set for the correct realm handling.

Note

Using this policy you can e.g. rewrite one realm to another realm on one client. Or you can define clients, where only users from a single realm, which is not the default realm, may authenticate without having to provide the realm name.

Returning Details on validation#

/validate endpoints can return additional information. On failed authentications LinOTP can return the reason the authentication failed. On successful authentications LinOTP can return additional information containing the username, the realm, the serial number of the token, that was used and the token type.

You can need to activate this behaviour using this policy.

  • Policy name: This is a unique name of the policy.

  • Scope: You need to set this to authorization.

  • Realm: Enter the name of the realm for which this policy should be valid. You can use “*” for all realms.

  • Action: You need to set this to either detail_on_success or detail_on_fail.

  • User: This is a list of users. Use “*” for all users.

  • Client: This is a list of IP addresses or IP subnets.