> ## Documentation Index
> Fetch the complete documentation index at: https://www.osohq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating Authentication (Identity) Data

Oso Cloud is authorization as a service. While similar in name, authentication
and authorization serve two different purposes:

* Authentication asserts *who* a user is.
* Authorization asserts *what* they can do.

This guide describes how to integrate Oso Cloud with your authentication
provider.

## What is authentication?

Authentication confirms the identity of a user. There are a variety of methods available
for confirming a user's identity, from a knowledge factor like
username and password combinations to more secure flows that include
possession factors or social logins and Single Sign-On (SSO) providers. Oso Cloud
is ***not*** an authentication provider, but it does integrate
easily with authentication providers.

## How Oso Cloud uses identities

Oso Cloud assumes that you are an authority for authenticating users and
that you store identity data, either in a data store or a hosted service.

In Oso Cloud, users are identified by a type and ID. If your application uses
universally unique identifiers (UUIDs), a user in Oso Cloud might look like
`User{"70f19088-7e97-4ca9-be0a-4deeaeedb7a7"}`.

For example, this is how you
could tell Oso Cloud that user `70f19...` has the `"admin"` role on a
particular organization:

```js theme={null}
const user = { type: "User", id: "70f19088-7e97-4ca9-be0a-4deeaeedb7a7" };
const organization = {
  type: "Organization",
  id: "00e54c4c-9bd3-4fc6-99d4-8d433e65d84f",
};

// User 70f19... has the "admin" role on Organization 00e54...
await oso.bulk([[], [["has_role", user, "admin", organization]]]);
```

That same user object can then be used to make an authorization
decision.

```js theme={null}
const allowed = await oso.authorize(user, "delete", organization);

if (allowed) {
  // Delete the organization.
} else {
  // Return an error.
}
```

### Choosing a user identifier

A good user identifier is:

* unique per user
* consistent for the same user over time
* accessible from any service in your system with minimal overhead

Examples:

* The `sub` property in the response from an authentication service or in a
  JSON Web Token (JWT).
* The `uuid` or `id` field on the `users` table in a relational datastore.

## Hands-on example

In this example, users can update projects by making `PUT` requests to the
`/api/project/[projectId]` endpoint. Here we use the front end framework NextJS,
Oso Cloud for authorization, and Stytch for authentication (though any authentication service
will work).

When a user logs in, Stytch stores a random string as a session token.
You authenticate the user's identity by validating the session token. The
decoded session object contains a `user_id` for the user, which we use to
identify the user to Oso Cloud:

```ts theme={null}
export async function updateProject(req: NextApiRequest, res: NextApiResponse<Response | Error>) {
  // Read the Stytch session token from the cookies.
  const token = cookies.get('stytch_session');

  // Authenticate the session token. Throws an error if the token is invalid.
  const resp = await loadStytch().sessions.authenticate({ session_token: token });

  // Retrieve the user ID from the decoded session.
  const userID = resp.session.user_id;
```

With the `user_id` from the session, we ask Oso Cloud if the user can update
the project:

```ts theme={null}
  // Retrieve the project ID from the request.
  const { projectId } = req.query;

  const user = { type: "User", id: userID };
  const project = { type: "Project", id: projectId };

  if (await oso.authorize(user, "update", project)) {
    // Update project.
  } else {
    // Return an error.
  }
}
```

### Do I need to sync all my users to Oso Cloud?

You do not need to sync users to Oso Cloud. Instead, you sync your users'
authorization data like roles and permissions. Oso Cloud uses those
roles and attributes to make
authorization decisions. Since Oso Cloud is deny by default, if you have not
synced any roles for a particular user, those authorization decisions
will be denied. For more information on adding facts to Oso Cloud, review
[the facts section of our documentation](/develop/facts/overview).

### What about scopes?

Some authentication services support scopes for users. Scopes are similar to
feature flags or global roles. They provide some data that you can use to
determine what a user can see or do. But they can only encode information about
the user and *not* about the resources in your application. For example, a user
might have the `delete_repository` scope that allows them to delete *any*
repository. However if you want to restrict users to only delete
repositories they own, a scope is insufficient.

Scopes might suffice if you only require coarse, global
access control, but they’re an incomplete solution that doesn’t support more
fine grained authorization.