Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/adonisjs-community/ally-starter-kit
A boilerplate to create your custom AdonisJS ally drivers.
https://github.com/adonisjs-community/ally-starter-kit
Last synced: about 1 month ago
JSON representation
A boilerplate to create your custom AdonisJS ally drivers.
- Host: GitHub
- URL: https://github.com/adonisjs-community/ally-starter-kit
- Owner: adonisjs-community
- Created: 2021-06-04T17:26:40.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-20T05:27:06.000Z (7 months ago)
- Last Synced: 2024-12-10T16:37:51.481Z (about 1 month ago)
- Language: TypeScript
- Homepage: https://docs.adonisjs.com/guides/auth/social
- Size: 17.6 KB
- Stars: 19
- Watchers: 2
- Forks: 55
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Ally driver boilerplate
> A boilerplate for creating custom AdonisJS Ally drivers
This repo is a starting point to create your custom OAuth2 drivers for [AdonisJS ally](https://docs.adonisjs.com/guides/authentication/social-authentication).
The boilerplate is tailored to create one driver per project and publish it as a package on npm.
## Getting started
Following are the steps to get started.
- Fork this repo and then clone it on your local machine.
- Install all the dependencies using `npm`, `pnpm`, or `yarn` (whatever you prefer).
- Open the `package.json` file and update the `name`, `description`, and the `author` details.
```json
{
"name": "ally-custom-service",
"description": "Starter kit to create an Ally driver for an OAuth2 service",
"author": ""
}
```
## How is the code structured?
The code for the driver is inside the `src` directory. Make sure to change the `YourDriver` keyword references inside the `src/driver.ts` file with the service name for which you are creating the driver. For example, Change `YourDriver` to `AppleDriver` or `InstagramDriver`.
The driver implementation is mainly driven by the config, except for the `user` and the `userFromToken` methods. Both of these methods are specific to the Oauth provider, so you have to implement them yourself.
The `src/driver.ts` file has the following exports.
#### YourDriverAccessToken
The type defines the properties on the access token returned by the driver. You must read your OAuth provider documentation and list all the properties here.
**Do not change the pre-defined `token` and `bearer` properties.**
```ts
export type YourDriverAccessToken = {
token: string
type: 'bearer'
}
```
#### YourDriverScopes
Define a union of driver scopes accepted by your OAuth provider. You can check out the [official implementations](https://github.com/adonisjs/ally/blob/next/src/types.ts#L237) to see how they are defined.
#### YourDriverConfig
The type defines the configuration options that your driver expects. It must specify the following properties and any additional properties your driver needs to be functional.
```ts
export type YourDriverConfig = {
driver: 'YourDriverName'
clientId: string
clientSecret: string
callbackUrl: string
authorizeUrl?: string
accessTokenUrl?: string
userInfoUrl?: string
}
```
#### YourDriver
The driver implementation is a standard TypeScript class that extends the base `Oauth2Driver` class. The base driver class forces you to define the following instance properties.
- `authorizeUrl` is the URL for the redirect request. The user is redirected to this URL to authorize the request. Check out provider docs to find this URL.
- `accessTokenUrl` is used to exchange the authorization code for the access token. Check out provider docs to find this URL.
- `userInfoUrl` is used to get the user profile information.
- `codeParamName` is the query string parameter for reading the **authorization code** after redirecting the user back to the callback URL.
- `errorParamName` is the query string parameter for finding the error after redirecting the user to the callback URL.
- `stateCookieName` is the cookie name for storing the CSRF token (also known as the state). Make sure the cookie name does not collide with other drivers. A safer option is to prefix the driver name followed by the `oauth_state` keyword.
- `stateParamName` is the query string parameter name for setting the state during the authorization redirect.
- `scopeParamName` is the query string parameter name for sending the scopes during the authorization redirect.
- `scopesSeparator` is the character used for separating multiple parameters.
#### YourDriverService
A factory function to reference the driver within the `config/ally.ts` file of an AdonisJS application. For example:
```ts
import { YourDriverService } from 'your-package-name'
defineConfig({
github: YourDriverService({
clientId: env.get('GITHUB_CLIENT_ID')!,
clientSecret: env.get('GITHUB_CLIENT_SECRET')!,
callbackUrl: '',
}),
})
```
## Development checklist
- [ ] I have renamed all `YourDriver` references to a more meaningful name inside the `src/driver.ts` file.
- [ ] I have defined the `authorizeUrl` class property.
- [ ] I have defined the `accessTokenUrl` class property.
- [ ] I have defined the `userInfoUrl` class property.
- [ ] I have defined the `codeParamName` class property.
- [ ] I have defined the `errorParamName` class property.
- [ ] I have defined the `stateCookieName` class property.
- [ ] I have defined the `stateParamName` class property.
- [ ] I have defined the `scopeParamName` class property.
- [ ] I have defined the `scopesSeparator` class property.
- [ ] I have implemented the `accessDenied` class method.
- [ ] I have implemented the `user` class method.
- [ ] I have implemented the `userFromToken` class method.
## Testing the driver
You can test the driver by installing it locally inside your AdonisJS application. Following are the steps you need to perform.
- Compile the TypeScript code to JavaScript using the `npm run build` script.
- `cd` into your AdonisJS project and install the package locally using `npm i path/to/your/driver/package`.
- Finally, reference the driver using the `YourDriverService` factory function inside the `config/ally.ts` file.
## FAQ's
### How do I define extra params during redirect?
You can configure the redirect request by implementing the `configureRedirectRequest` method on the driver class. The method is already pre-defined and commented out.
```ts
protected configureRedirectRequest(request: RedirectRequest) {
request.param('key', 'value')
}
```
### How do I define extra fields/params for the access token request?
You can configure the access token request by implementing the `configureAccessTokenRequest` method on the driver class. The method is already pre-defined and commented out.
```ts
protected configureAccessTokenRequest(request: ApiRequest) {
// Request body
request.field('key', 'value')
// Query param
request.param('key', 'value')
}
```
## Share with others
Are you excited about sharing your work with others? Submit your package to the [awesome-adonisjs](https://github.com/adonisjs-community/awesome-adonisjs) repo.