AccessProvider.create()

Learn: Access providers

We recommend you use FSL to create and update access providers. See FSL access provider schema.

Creates an access provider in an FQL query.

Signature

AccessProvider.create(data: {*: Any}) => AccessProvider

Description

The AccessProvider.create() method creates an AccessProvider document with the provided data. The provider document controls access to the current database by a third-party identity provider (IdP), such as Auth0.

After an AccessProvider document is created and the IdP is configured, callers can authenticate using the IdP service, then access Fauna resources as configured by the document.

Considerations

If a database has staged schema, this method adds an access provider to the staged schema, not the active schema.

If the database has no staged schema, using this method is equivalent to making an unstaged schema change. Changes are applied immediately to the database’s active schema.

Avoid concurrent schema changes

Concurrent unstaged schema changes can cause contended transactions, even if the changes affect different resources. This includes unstaged changes made using:

A schema change triggers a transaction that validates the entire database schema. To avoid errors, do one of the following instead:

Parameters

Parameter Type Required Description

data

Object

Object describing the access provider.

data fields

Name Type Required Description

name

String

Yes

Unique external identity provider (IdP) name. Can’t be events, sets, self, documents, or underscore (_) character and can’t include the percent (%) character.

issuer

String

Unique IdP HTTPS URL used to grant access to Fauna, typically, an account or application URL supplied by the IdP. Use an exact copy of the IdP issuer URL, including a trailing slash (/) if it exists.

jwks_uri

String

Valid HTTPS URI. This should be the JSON Web Key (JWK) that signs the JSON Web Token (JWT) from the IdP.

roles

Null OR String OR Object OR Array

Roles to evaluate JWT token access. No privileges are defined if roles is omitted and queries with JWT tokens from issuer can’t be processed.

If a predicate is defined, the predicate must use long form syntax.

If roles is a single role string, it has the following format:

roles: 'developers'

If roles is an Array of role strings, it has the following format:

roles: [
  'developers',
  'managers'
]

If roles is a single role:predicate object, it has the following format:

"roles": {
  "role": "customers",
  "predicate": "_ => true"
}

If roles is an Array of role:predicate objects, it has the following format:

"roles": [
  {
    "role": "customers",
    "predicate": "_ => true"
  },
  ...
]

The predicate function is passed an object representing the JWT token payload field, which includes claims. How the claims are interpreted depends on the IdP. See https://jwt.io/introduction/ or your IdP documentation for more information.

If the predicate function returns true, the role is evaluated to grant or deny access needed to execute the query.

data

Object

User-defined AccessProvider metadata to store supplemental information.

Return value

An object with metadata for the results of the create() call.

Type Description

AccessProvider

New access provider.
See AccessProvider

Examples

AccessProvider.create({
  name: "someIssuer",
  issuer: "https://example.com/",
  jwks_uri: "https://example.com/.well-known/jwks.json",
  roles: [
    "customer",
    {
      role: "manager",
      predicate: "(jwt) => jwt!.scope.includes(\"manager\")"
    }
  ],
  data: {
    desc: "Access provider for issuer"
  }
})
{
  name: "someIssuer",
  coll: AccessProvider,
  ts: Time("2099-06-25T13:08:04.020Z"),
  issuer: "https://example.com/",
  audience: "https://db.fauna.com/db/ysjons5xryyr4",
  data: {
    desc: "Access provider for issuer"
  },
  jwks_uri: "https://example.com/.well-known/jwks.json",
  roles: [
    "customer",
    {
      role: "manager",
      predicate: "(jwt) => jwt!.scope.includes(\"manager\")"
    }
  ]
}

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!