CreateAccessProvider

CreateAccessProvider( param_object )
CreateAccessProvider( param_object )
create_access_provider( param_object )
CreateAccessProvider( param_object )

Description

CreateAccessProvider creates a new AccessProvider document, based on the settings in param_object, which can be used to control access to the current database via a third-party identity provider (IdP) , such as Auth0.

Once an AccessProvider has been created and your IdP has been configured properly, users can authenticate via the authentication service and then access Fauna. This avoid having to handle authentication yourself, via Login or by managing Keys.

Parameters

Parameter Type Definition and Requirements

param_object

Object

The param_object fields are described below.

param_object

Field Name Field Type Definition and Requirements

name

String

A unique name for the AccessProvider.

Cannot be events, sets, self, documents, or _. Cannot have the % character.

issuer

String

An HTTPS URL for the IdP that you are using to grant access to Fauna. This is typically an account-/app-specific URL that your IdP provides.

Use an exact copy of your IdP’s issuer URL, including a trailing slash (if there is one). URL differences could prevent Fauna acceptance of your IdP’s JWT tokens.

jwks_uri

String

A valid HTTPS URI, which should serve the JSON Web Key that signs the JWT tokens from your IdP.

roles

Array of Role References or Role-predicate objects.

Optional - Defines the roles that should be evaluated to determine access for a provided JWT token.

When roles is not specified, no privileges are defined — queries with JWT tokens from the specified issuer cannot be processed.

The usual use of roles is to specify a list of one or more Role references:

roles: [ Role('developers'), Role('managers') ]

Per overlapping roles, any role that grants access means that the query involving a JWT token is processed, even if another Role might deny access.

A Role-predicate object specifies a Role to potentially evaluate, whose evaluation is determined by the specified predicate function:

{
  role: Role('executives'),
  predicate: Query(Lambda("accessToken", ... )),
}

The predicate function is passed an object representing the payload field from the JWT token. The payload field contains claims, which are statements about the user represented by the JWT token. How these claims are specified/interpreted can vary depending on the IdP. See https://jwt.io/introduction/ for background information, and your IdP’s documentation, for more details.

The predicate function must return a boolean value, and if the result is true, the specified Role is evaluated to determine whether the access required to execute the query (in the request accompanying the JWT token) has been granted.

data

Object

Optional - Contains user-defined metadata for the AccessProvider. It is provided for the developer to store AccessProvider-relevant information.

ttl

Timestamp

Optional - A timestamp that indicates the time-to-live for a document, which is when the document is removed from the collection and can’t be queried. The document history can continue to be accessed using the Events function, provided the events are in the history retention interval and the document reference is input to the Events function.

Returns

An object containing the metadata about the results of CreateAccessProvider operations.

Field Name Field Type Definition and Requirements

ref

Reference

The reference is an automatically-generated, unique identifier within the database to the AccessProvider that was created.

ts

Long

The timestamp, with microsecond resolution, associated with the creation of the AccessProvider.

name

String

The name for this AccessProvider.

issuer

String

The issuer value that was provided when creating the AccessProvider.

jwks_uri

String

The jwks_uri value that was provided when creating the AccessProvider.

audience

String

A database-specific HTTP URI. Queries that should be authenticated using a JWT token should use this URI, instead of the default https://db.fauna.com/ successful login.

Every AccessProvider for the current database shares the same audience URI.

Examples

result, err := client.Query(
	f.CreateAccessProvider(
		f.Obj{
			"name": "Auth0-myapp",
			"issuer": "https://myapp.auth0.com/",
			"jwks_uri": "https://myapp.auth0.com/.well-known/jwks.json",
		},
	))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[audience:https://db.fauna.com/db/yomix74weybyy issuer:https://myapp.auth0.com/ jwks_uri:https://myapp.auth0.com/.well-known/jwks.json name:Auth0-myapp ref:{Auth0-myapp 0xc0002001e0 0xc0002001e0 <nil>} ts:1617403014570000]
client.query(
  q.CreateAccessProvider({
    name: 'Auth0-myapp',
    issuer: 'https://myapp.auth0.com/',
    jwks_uri: 'https://myapp.auth0.com/.well-known/jwks.json',
  })
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: AccessProvider("Auth0-myapp"),
  ts: 1604524688650000,
  name: 'Auth0-myapp',
  issuer: 'https://myapp.auth0.com/',
  jwks_uri: 'https://myapp.auth0.com/.well-known/jwks.json',
  audience: 'https://db.fauna.com/db/yxuihtdghybyy'
}
result = client.query(
  q.create_access_provider({
    "name": 'Auth0-myapp',
    "issuer": 'https://myapp.auth0.com/',
    "jwks_uri": 'https://myapp.auth0.com/.well-known/jwks.json',
  })
)
print(result)
{'ref': Ref(id=Auth0-myapp, collection=Ref(id=access_providers)), 'ts': 1611103252110000, 'name': 'Auth0-myapp', 'issuer': 'https://myapp.auth0.com/', 'jwks_uri': 'https://myapp.auth0.com/.well-known/jwks.json', 'audience': 'https://db.fauna.com/db/yx96yn6haydyy'}
CreateAccessProvider({
  name: 'Auth0-myapp',
  issuer: 'https://myapp.auth0.com/',
  jwks_uri: 'https://myapp.auth0.com/.well-known/jwks.json',
})
{
  ref: AccessProvider("Auth0-myapp"),
  ts: 1624449336520000,
  name: 'Auth0-myapp',
  issuer: 'https://myapp.auth0.com/',
  jwks_uri: 'https://myapp.auth0.com/.well-known/jwks.json',
  audience: 'https://db.fauna.com/db/yoa3xz8xoybyy'
}
Query metrics:

  •    bytesIn:  155

  •   bytesOut:  287

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:  232

  • writeBytes:  587

  •  queryTime: 12ms

  •    retries:    0

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!