Auth Service
This service deals with the generation and verification of tokens and their associated representations as credentials objects. You can use it for validating incoming tokens, and generating tokens for calling other services.
If you want to deal with credentials specifically in the HTTP request/response
flow, see also the httpAuth
service. If you want to extract
more details about authenticated users such as their ownership entity refs, use
the userInfo
service.
Using the Service
In the following code examples, the auth
and httpAuth
variables are assumed
to be dependency-injected instances of the coreServices.auth
and
coreServices.httpAuth
service, respectively. For a backend plugin, it might
look like this:
export default createBackendPlugin({
pluginId: 'my-plugin',
register(env) {
env.registerInit({
deps: {
auth: coreServices.auth,
httpAuth: coreServices.httpAuth,
httpRouter: coreServices.httpRouter,
},
async init({ auth, httpAuth, httpRouter }) {
// Your code goes here
},
});
},
});
Creating Request Tokens
If you need to create a token that can be used for making a request to another backend plugin:
const { token } = await auth.getPluginRequestToken({
onBehalfOf: await auth.getOwnServiceCredentials(),
targetPluginId: 'catalog',
});
Never store and reuse tokens. Always call getPluginRequestToken
immediately
before making a request. Otherwise you run the risk of running into permission
problems when expired tokens are being used for requests.
This example is suitable when you need to make the request "as your own plugin", i.e. when your code is the original initiator of the call. An example of this could be periodic batch processes that index content in another service.
In situations where you are making a call on-behalf-of someone else, for example when making upstream requests inside a request handler, please always instead use the extracted credentials from the request.
router.get('/makes-calls', async (req, res) => {
const { token } = await auth.getPluginRequestToken({
onBehalfOf: await httpAuth.credentials(req),
targetPluginId: 'catalog',
});
});
// make a call using the token
This ensures that the original caller and their associated permissions are
properly carried along with the request chain. See the httpAuth
service docs
for more details.
The service to service auth docs contain more details about how to properly use tokens in your HTTP request paths.
Authorizing Tokens
Most plugins should not deal with incoming request tokens directly at all, but
rather use httpAuth.credentials
instead as part of their
request handlers. But in the rare cases where you are holding an incoming token
and want to validate it and turn it into a credentials object, you can do so:
const credentials = await auth.authenticate(token);
There is an optional second parameter that you can set to { allowLimitedAccess: true }
if you specifically built a plugin that deals with cookie based access,
which is rare.
Inspecting Credentials
The auth
service also contains facilities for working with credentials
objects. For example checking what type of principal (caller type - e.g. user or
service) they represent. For example:
if (auth.isPrincipal(credentials, 'user')) {
// In here, the TypeScript type of the credentials object has been properly
// narrowed to `BackstageCredentials<BackstageUserPrincipal>` so you can
// access its specific properties such as `credentials.principal.userEntityRef`.
}
Configuring the service
The auth
service is not suitable for having its implementation replaced
entirely in your private repo. If you desire additional service auth related
features, don't hesitate to file an issue
or contribute to the open source features.
For configuring service-to-service access methods, see the auth docs.
The default auth policy requires all requests to be authenticated with either
user or service credentials. This can be disabled by setting the
backend.auth.dangerouslyDisableDefaultAuthPolicy
app-config flag to true
.
Disabling this check means that the backend will no longer block unauthenticated
requests, but instead allow them to pass through to plugins. Do not do this in
production unless absolutely necessary.
If permissions are enabled, unauthenticated requests will be treated exactly as such, leaving it to the permission policy to determine what permissions should be allowed for an unauthenticated identity. Note that this will also apply to service-to-service calls between plugins unless you configure credentials for service calls.