Authentication Policy Examples

Policy on the realm auth::/oauth2/http determines which requesters can obtain a user access token that allows invocation of other resources in the system. Tokens are issued to client endpoints APC/API, web console, and NATS.

System-defined users

When a cluster is initially created, you designate and configure one or more administrative or operations users. Such users are given membership in the admin role which grants full permissions to all cluster resources. It is the responsibility of these users to create policy that allows other users to access the system.

The following examples show how to use policy to add such users to the system. Users are added using auth realm permissions. These examples use the default Google authentication facility that comes with a production cluster.

users.pol

To create users, the typical approach is to create a policy document called users.pol. Then, for every new user, you create a policy in the users.pol file that authenticates that user. Once you have created the users, typically you map users to roles and grant permissions.

Token issuance

The following policy rule permits issuance of a token to the requester when Google asserts the requester has an email address of tom@gmail.com. The token allows the user to access the system. However, it does not allow the user to do anything. Policy must be applied authorizing system use by resource type.

The rule also sets the name in the issued token to tom. The name value can be any string and is used to refer to the user in the system.

auth::/oauth2/http {
  if (Google->email == "tom@gmail.com") {
    permit issue
    name "tom"
  }
}

Once the token is issued, you grant the user permissions individually or using roles.

The name claim and value is required. If you use an email address as the name, the system truncates the name value for the initial namespace.

For example, if the following policy is created, the user is authenticated and assigned the name some-person@gmail.com:

auth::/oauth2/http {
  if (Google->email == "some-person@gmail.com") {
    permit issue
    name "some-person@gmail.com"
  }
}

This policy states that if the Auth Server asserts that Google Auth has identified the user as some-person@gmail.com, the policy engine permits token issuance and assigns the string some-person@gmail.com as the subject of the token. In this case, the user is placed in the /sandbox/some-person namespace.

Multiple user example

The following policy block creates multiple users. Each rule tells the system to issue a token to the requester when Google asserts the requester has the specified email address and sets the name in the issued token to the name value.

auth::/oauth2/http {
  if (Google->email == "tom@gmail.com") {
    permit issue
    name "tom"
  }
  if (Google->email == "bob@gmail.com") {
    permit issue
    name "bob"
  }
}

Default namespace example

Default namespace is set on the root auth::/ realm. The following example somewhat superfluously sets the default namespace for each user to the namespace that would have been generated by the system automatically.

auth::/ {
  if (auth_server@apcera.me->name == "tom") {
    defaultNamespace "/sandbox/tom"
  }
  if (auth_server@apcera.me->name == "bob") {
    defaultNamespace "/sandbox/bob"
  }
}

User access policy

When a cluster is initially created, one or more administrative or operations users is defined and granted full permissions on all cluster resources. These users then create policy to allow other users to access the system.

To grant new users access to the system, typically you will create an authPolicy.pol policy document that contains policy which authorizes the issuance of a token to an authenticated user.

For example, the following policy allows the Google user to be issued a token to log in to the system:

auth::/oauth2/http {
  if (Google->email == "josh@acme.com") {
    name "josh"
    permit issue
  }
}

Typically you will then create a policy document called roleMembership.pol that maps users to roles. See Role Based Access Control for guidance.