Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fixes typos in the quickstart/backend directory #10391

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion articles/quickstart/backend/_includes/_api_create.html
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
<% if (account.userName) { %>
<p>In the APIs section in <a href="${manage_url}/#/">dashboard</a>, click the <strong>Create API</strong> button. Provide a <strong>Name</strong> and <strong>Identifier</strong> for your API. You must choose the RS256 <a href="/tokens/concepts/signing-algorithms">signing algorithm</a>. Once it is created, navigate to the <strong>Scopes</strong> tab and create the applicable scopes for your API.</p>
<% } else { %>
<p>Create an <a href="${manage_url}/login">Auth0 account</a> (or login) navigate to the APIs section in <a href="${manage_url}/#/">Dashboard</a>. Click the <strong>Create API</strong> button and provide a <strong>Name</strong> and <strong>Identifier</strong> for your API. You must choose the RS256 <a href="/tokens/concepts/signing-algorithms">signing algorithm</a>. Once it is created, navigate to the <strong>Scopes</strong> tab and create the applicable scopes for your API.</p>
<p>Create an <a href="${manage_url}/login">Auth0 account</a> (or log in) navigate to the APIs section in <a href="${manage_url}/#/">Dashboard</a>. Click the <strong>Create API</strong> button and provide a <strong>Name</strong> and <strong>Identifier</strong> for your API. You must choose the RS256 <a href="/tokens/concepts/signing-algorithms">signing algorithm</a>. Once it is created, navigate to the <strong>Scopes</strong> tab and create the applicable scopes for your API.</p>
<% } %>
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ A quick way to inspect a JWT is by using the [JWT.io](https://jwt.io/) website.

![Debugging a JWT on JWT.io](/media/articles/server-apis/aspnet-core-webapi/jwt-io-debugger-rs256.png)

In the screenshot above you can see that the token was signed using the **RS256** algorithm. The **Issuer** of the token is **https://jerrie.auth0.com/**, and the **Audience** is **https://rs256.test.api**.
In the screenshot above, you can see that the token was signed using the **RS256** algorithm. The **Issuer** of the token is **https://jerrie.auth0.com/**, and the **Audience** is **https://rs256.test.api**.

So, in other words, these values in your JWT validation configuration registration must match **exactly** - including the trailing slash for the Issuer, such as

Expand All @@ -42,5 +42,5 @@ For a token signed using HS256, the debugger view will look a little different:

![Debugging a JWT on JWT.io](/media/articles/server-apis/aspnet-core-webapi/jwt-io-debugger-hs256.png)

In the screenshot above you can see that the token was signed using the **HS256** algorithm. The **Issuer** of the token is **https://jerrie.auth0.com/**, and the **Audience** is **https://hs256.test.api**.
In the screenshot above, you can see that the token was signed using the **HS256** algorithm. The **Issuer** of the token is **https://jerrie.auth0.com/**, and the **Audience** is **https://hs256.test.api**.

6 changes: 3 additions & 3 deletions articles/quickstart/backend/_includes/_api_using.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,12 @@ You can call the API from your application by passing an Access Token in the `Au

## Obtaining an Access Token

If you are calling the API from a Single-Page Application or a Mobile/Native application, after the authorization flow is completed, you will get an Access Token. How you get the token and how you make the call to the API will be dependent on the type of application you are developing and the framework you are using. For more information refer to the relevant application Quickstarts which contain detailed instructions:
If you are calling the API from a Single-Page Application or a Mobile/Native application, after the authorization flow is completed, you will get an Access Token. How you get the token and how you make the call to the API will be dependent on the type of application you are developing and the framework you are using. For more information, refer to the relevant application Quickstarts which contain detailed instructions:

* [Single-Page Applications](/quickstart/spa)
* [Mobile / Native Application](/quickstart/native)

If you are calling the API from a command-line tool or another service, where there isn't a user entering their credentials, you need to use the [OAuth Client Credentials flow](/api/authentication#client-credentials). To do that, register a [Machine to Machine Application](${manage_url}/#/applications), and then subsequently use the **Client ID** and **Client Secret** of this application when making the request below and pass those along in the `client_id` and `client_secret` parameters respectively. Also include the Audience for the API you want to call.
If you are calling the API from a command-line tool or another service, where there isn't a user entering their credentials, you need to use the [OAuth Client Credentials flow](/api/authentication#client-credentials). To do that, register a [Machine-to-Machine Application](${manage_url}/#/applications), and then subsequently use the **Client ID** and **Client Secret** of this application when making the request below and pass those along in the `client_id` and `client_secret` parameters, respectively. Also include the Audience for the API you want to call.

:::note
Read [Application Settings](https://auth0.com/docs/get-started/dashboard/application-settings) for more information on getting the Client ID and Client Secret for your machine-to-machine app.
Expand Down Expand Up @@ -59,7 +59,7 @@ Read [Application Settings](https://auth0.com/docs/get-started/dashboard/applica
```

:::note
Auth0 customers are billed based on the number of Machine to Machine Access Tokens issued by Auth0. Once your application gets an Access Token it should keep using it until it expires, to minimize the number of tokens requested.
Auth0 customers are billed based on the number of Machine-to-Machine Access Tokens issued by Auth0. Once your application gets an Access Token, it should keep using it until it expires, to minimize the number of tokens requested.
:::

For testing purposes, you can also get an Access Token from the **Test** tab in your [API settings](${manage_url}/#/apis).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ The ASP.NET Core JWT Bearer authentication handler downloads the JSON Web Key Se
In your application, register the authentication services:

1. Make a call to the `AddAuthentication` method. Configure `JwtBearerDefaults.AuthenticationScheme` as the default schemes.
2. Make a call to the `AddJwtBearer` method to register the JWT Bearer authentication scheme. Configure your Auth0 domain as the authority, and your Auth0 API identifier as the audience. In some cases the access token will not have a `sub` claim which will lead to `User.Identity.Name` being `null`. If you want to map a different claim to `User.Identity.Name` then add it to `options.TokenValidationParameters` within the `AddAuthentication()` call.
2. Make a call to the `AddJwtBearer` method to register the JWT Bearer authentication scheme. Configure your Auth0 domain as the authority, and your Auth0 API identifier as the audience. In some cases, the access token will not have a `sub` claim which will lead to `User.Identity.Name` being `null`. If you want to map a different claim to `User.Identity.Name`, then add it to `options.TokenValidationParameters` within the `AddAuthentication()` call.

```csharp
// Program.cs
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This document will help you troubleshoot your JWT middleware configuration.

## Check the Token Validation

There are 5 criteria for validating a JWT token.
There are five criteria for validating a JWT token.

1. **Is the token formed properly?**
Check if the structure of the token matches the structure of a JSON Web Token. Read more about the [JSON Web Token structure](/jwt#what-is-the-json-web-token-structure-).
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
To run the sample you need [.NET Core](https://www.microsoft.com/net/download) installed, and run the following commands:
To run the sample, you need [.NET Core](https://www.microsoft.com/net/download) installed, and run the following commands:

```bash
dotnet restore
Expand Down
2 changes: 1 addition & 1 deletion articles/quickstart/backend/django/01-authorization.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ def requires_scope(required_scope):

<%= include('../_includes/_api_endpoints') %>

In the file `views.py` add `public` and `private` endpoints. Add the `@api_view` decorator to all the endpoints to indicate that the method requires authentication. Lastly, add the decorator `@permission_classes([AllowAny])` to the `public` endpoint to accept unauthenticated requests.
In the file `views.py`, add `public` and `private` endpoints. Add the `@api_view` decorator to all the endpoints to indicate that the method requires authentication. Lastly, add the decorator `@permission_classes([AllowAny])` to the `public` endpoint to accept unauthenticated requests.

```python
# auth0authorization/views.py
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ This Quickstart uses Spring MVC. If you are using Spring WebFlux, the steps to s

## Configure the Sample Project

The sample project uses a `/src/main/resources/application.yml` file, which configures it to use the correct Auth0 **Domain** and **API Identifier** for your API. If you download the code from this page it will be automatically configured. If you clone the example from GitHub, you will need to fill it in yourself.
The sample project uses a `/src/main/resources/application.yml` file, which configures it to use the correct Auth0 **Domain** and **API Identifier** for your API. If you download the code from this page, it will be automatically configured. If you clone the example from GitHub, you will need to fill it in yourself.

```yaml
okta:
Expand All @@ -40,7 +40,7 @@ okta:

| Attribute | Description|
| --- | --- |
| `okta.oauth2.audience` | The unique identifier for your API. If you are following the steps in this tutorial it would be `https://quickstarts/api`. |
| `okta.oauth2.audience` | The unique identifier for your API. If you are following the steps in this tutorial, it would be `https://quickstarts/api`. |
| `okta.oauth2.issuer` | The issuer URI of the resource server, which will be the value of the `iss` claim in the JWT issued by Auth0. Spring Security will use this property to discover the authorization server's public keys and validate the JWT signature. The value will be your Auth0 domain with an `https://` prefix and a `/` suffix (the trailing slash is important). |

## Install dependencies
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
/*
This is where we configure the security required for our endpoints and setup our app to serve as
This is where we configure the security required for our endpoints and set up our app to serve as
an OAuth2 Resource Server, using JWT validation.
*/
return http
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,11 +35,11 @@ Each Auth0 API uses the API Identifier, which your application needs to validate

## Configure the sample project {{{ data-action=code data-code="application.yml#1:8" }}}

The sample project uses a `/src/main/resources/application.yml` file, which configures it to use the correct Auth0 **domain** and **API Identifier** for your API. If you download the code from this page it will be automatically configured. If you clone the example from GitHub, you will need to fill it in yourself.
The sample project uses a `/src/main/resources/application.yml` file, which configures it to use the correct Auth0 **domain** and **API Identifier** for your API. If you download the code from this page, it will be automatically configured. If you clone the example from GitHub, you will need to fill it in yourself.

| Attribute | Description|
| --- | --- |
| `okta.oauth2.audience` | The unique identifier for your API. If you are following the steps in this tutorial it would be `https://quickstarts/api`. |
| `okta.oauth2.audience` | The unique identifier for your API. If you are following the steps in this tutorial, it would be `https://quickstarts/api`. |
| `okta.oauth2.issuer` | The issuer URI of the resource server, which will be the value of the `iss` claim in the JWT issued by Auth0. Spring Security will use this property to discover the authorization server's public keys and validate the JWT signature. The value will be your Auth0 domain with an `https://` prefix and a `/` suffix (the trailing slash is important).

## Install dependencies {{{ data-action=code data-code="application.yml#1:8" }}}
Expand Down
2 changes: 1 addition & 1 deletion articles/quickstart/backend/laravel/01-authorization.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ You should also create a new API:

This produces two files in your project directory that configure the SDK.

As these files contain credentials it's important to treat these as sensitive. You should ensure you do not commit these to version control. If you're using Git, you should add them to your `.gitignore` file:
As these files contain credentials, it's important to treat these as sensitive. You should ensure you do not commit these to version control. If you're using Git, you should add them to your `.gitignore` file:

```bash
echo ".auth0.*.json" >> .gitignore
Expand Down
10 changes: 5 additions & 5 deletions articles/quickstart/backend/laravel/interactive.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ As their name implies, [access tokens](https://auth0.com/docs/secure/tokens/acce
composer create-project --prefer-dist laravel/laravel auth0-laravel-api ^9.0
```

All the commands in this guide assume you are running them from the root of your Laravel project, directory so you should `cd` into the new project directory:
All the commands in this guide assume you are running them from the root of your Laravel project directory, so you should `cd` into the new project directory:

```shell
cd auth0-laravel-api
Expand All @@ -54,7 +54,7 @@ Run the following command within your project directory to install the [Auth0 La
composer require auth0/login:^7.8 --update-with-all-dependencies
```

Then generate an SDK configuration file for your application:
Then, generate an SDK configuration file for your application:

```shell
php artisan vendor:publish --tag auth0
Expand All @@ -68,7 +68,7 @@ Run the following command from your project directory to download the [Auth0 CLI
curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .
```

Then authenticate the CLI with your Auth0 account, choosing "as a user" when prompted:
Then, authenticate the CLI with your Auth0 account, choosing "as a user" when prompted:

```shell
./auth0 login
Expand Down Expand Up @@ -101,7 +101,7 @@ You should also create a new API:

This produces two files in your project directory that configure the SDK.

As these files contain credentials it's important to treat these as sensitive. You should ensure you do not commit these to version control. If you're using Git, you should add them to your `.gitignore` file:
As these files contain credentials, it's important to treat them as sensitive. You should ensure you do not commit them to version control. If you're using Git, you should add them to your `.gitignore` file:

```bash
echo ".auth0.*.json" >> .gitignore
Expand Down Expand Up @@ -163,7 +163,7 @@ Route::get('/', function () {

You can retrieve information about the user who created the access token from Auth0 using the [Auth0 Management API](https://github.com/auth0/laravel-auth0/blob/main/docs/Management.md). The SDK provides a convenient wrapper for this API, accessible through the SDK's `management()` method.

**Before making Management API calls you must enable your application to communicate with the Management API.** This can be done from the [Auth0 Dashboard's API page](https://manage.auth0.com/#/apis/), choosing `Auth0 Management API`, and selecting the 'Machine to Machine Applications' tab. Authorize your Laravel application, and then click the down arrow to choose the scopes you wish to grant.
**Before making Management API calls, you must enable your application to communicate with the Management API.** This can be done from the [Auth0 Dashboard's API page](https://manage.auth0.com/#/apis/), choosing `Auth0 Management API`, and selecting the 'Machine to Machine Applications' tab. Authorize your Laravel application, and then click the down arrow to choose the scopes you wish to grant.

For the following example, you should grant the `read:users` scope. A list of API endpoints and the required scopes can be found in [the Management API documentation](https://auth0.com/docs/api/management/v2).

Expand Down
2 changes: 1 addition & 1 deletion articles/quickstart/backend/php/01-authorization.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ if ($jwt !== null) {
define('ENDPOINT_AUTHORIZED', true);
} catch (\Auth0\SDK\Exception\InvalidTokenException $exception) {
// The token wasn't valid. Let's display the error message from the Auth0 SDK.
// We'd probably want to show a custom error here for a real world application.
// We'd probably want to show a custom error here for a real-world application.
die($exception->getMessage());
}
}
Expand Down
6 changes: 3 additions & 3 deletions articles/quickstart/backend/python/interactive.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,21 +48,21 @@ The validator will validate the Access Token that we pass to the resource by che

We can use AuthLib's `JWTBearerTokenValidator` validator with a few tweaks to make sure it conforms to our requirements on [validating Access Tokens](https://auth0.com/docs/secure/tokens/access-tokens/validate-access-tokens).

To create our `Auth0JWTBearerTokenValidator` we need to pass it our `domain` and `audience` (API Identifier). It will then get the public key required to verify the token's signature and pass it to the `JWTBearerTokenValidator` class.
To create our `Auth0JWTBearerTokenValidator`, we need to pass it our `domain` and `audience` (API Identifier). It will then get the public key required to verify the token's signature and pass it to the `JWTBearerTokenValidator` class.

We'll then override the class's `claims_options` to make sure the token's expiry, audience and issue claims are validated according to our requirements.

## Create a Flask application {{{ data-action=code data-code="server.py" }}}

Next we'll create a Flask application with 3 API routes:
Next, we'll create a Flask application with 3 API routes:

- `/api/public` A public endpoint that requires no authentication.
- `/api/private` A private endpoint that requires a valid Access Token JWT.
- `/api/private-scoped` A private endpoint that requires a valid Access Token JWT that contains the given `scope`.

The protected routes will have a `require_auth` decorator which is a `ResourceProtector` that uses the `Auth0JWTBearerTokenValidator` we created earlier.

To create the `Auth0JWTBearerTokenValidator` we'll pass it our tenant's domain and the API Identifier of the API we created earlier.
To create the `Auth0JWTBearerTokenValidator`, we'll pass it our tenant's domain and the API Identifier of the API we created earlier.

The `require_auth` decorator on the `private_scoped` route accepts an additional argument `"read:messages"`, which checks the Access Token for the Permission (Scope) we created earlier.

Expand Down
4 changes: 2 additions & 2 deletions articles/quickstart/backend/rails/01-authorization.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ class Auth0Client
end
```

Next, in the `Secured` concern, define a new error constant `INSUFFICIENT_PERMISSIONS` to return a proper error message in case there was a attempt to request a resource without the right permissions. Next, update the return value of the `Auth0Client.validate_token` call and finally create a new method `validate_permissions` where to check if the token has the right permissions, or return a `403 FORBIDDEN` status code with the `INSUFFICIENT_PERMISSIONS` error message otherwise.
Next, in the `Secured` concern, define a new error constant `INSUFFICIENT_PERMISSIONS` to return a proper error message in case there was a attempt to request a resource without the right permissions. Next, update the return value of the `Auth0Client.validate_token` call, and finally, create a new method `validate_permissions` where to check if the token has the right permissions, or return a `403 FORBIDDEN` status code with the `INSUFFICIENT_PERMISSIONS` error message otherwise.

Apply these changes in your `Secured` concern by adding the following code:

Expand Down Expand Up @@ -256,7 +256,7 @@ class ApplicationController < ActionController::API
end
```

You only ned to protect the `PrivateController` as follows:
You only need to protect the `PrivateController` as follows:

```ruby
class PrivateController < ApplicationController
Expand Down