diff --git a/.changeset/twenty-clocks-retire.md b/.changeset/twenty-clocks-retire.md deleted file mode 100644 index ca6fa8b..0000000 --- a/.changeset/twenty-clocks-retire.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -'@asgardeo/remix-auth-asgardeo': patch ---- - -### v0.0.2 🎉 - -- Add README to the released artifact. diff --git a/lib/CHANGELOG.md b/lib/CHANGELOG.md index 333f377..f6455bb 100644 --- a/lib/CHANGELOG.md +++ b/lib/CHANGELOG.md @@ -1,5 +1,15 @@ # @asgardeo/remix-auth-asgardeo +## 0.0.2 + +### Patch Changes + +- [#9](https://github.com/asgardeo/remix-auth-asgardeo/pull/9) + [`cc2c1d0`](https://github.com/asgardeo/remix-auth-asgardeo/commit/cc2c1d05a635038ef742479d4f88a7af6f1f10d9) Thanks + [@brionmario](https://github.com/brionmario)! - ### v0.0.2 🎉 + + - Add README to the released artifact. + ## 0.0.1 ### Patch Changes diff --git a/lib/README.md b/lib/README.md new file mode 100644 index 0000000..429d518 --- /dev/null +++ b/lib/README.md @@ -0,0 +1,137 @@ +

+

Remix Auth Asgardeo

+

+ +
+ 🚀 Release + 🧱 Builder + + Stackoverflow + Discord + License + Twitter +
+ +
+ +[Remix Auth](https://remix.run/resources/remix-auth) is a flexible authentication framework for [Remix](https://remix.run/) applications that allows developers to implement various strategies for user authentication. + +The Asgardeo strategy is a custom implementation of the [OAuth2Strategy](https://github.com/sergiodxa/remix-auth-oauth2) designed specifically for integrating with [Asgardeo](https://wso2.com/asgardeo), an identity-as-a-service (IDaaS) platform. This strategy enables developers to authenticate users against an Asgardeo organization using OpenID Connect (OIDC). + +## Supported runtimes + +| Runtime | Has Support | +| ---------- | ----------- | +| Node.js | ✅ | +| Cloudflare | ✅ | + +## How to use + +### Create an Asgardeo organization + +Head over to [Asgardeo](https://wso2.com/asgardeo) and sign up for an organization. + +### Register an application + +Follow the steps on the [Asgardeo documentation](https://wso2.com/asgardeo/docs/guides/applications/register-oidc-web-app/) to create an application and get the client ID, and client secret. + +### Create the Asgardeo strategy instance + +```ts +// app/utils/asgardeo.server.ts +import { Authenticator } from "remix-auth"; +import { AsgardeoStrategy } from "remix-auth-asgardeo"; + +// Create an instance of the authenticator, pass a generic with what your +// strategies will return and will be stored in the session +export const authenticator = new Authenticator(sessionStorage); + +let asgardeoStrategy = new AsgardeoStrategy( + { + authorizedRedirectUrl: "http://localhost:5173/auth/asgardeo/callback", + clientID: "YOUR_ASGARDEO_CLIENT_ID", + clientSecret: "YOUR_ASGARDEO_CLIENT_SECRET", + baseUrl: "https://api.asgardeo.io/t/", + }, + async ({ accessToken, refreshToken, extraParams, profile }) => { + // Get the user data from your DB or API using the tokens and profile + return User.findOrCreate({ email: profile.emails[0].value }); + } +); + +authenticator.use(asgardeoStrategy); +``` + +### Setup application routes + +```ts +// app/routes/login.tsx +export default function Login() { + return ( +
+ +
+ ); +} +``` + +```ts +// app/routes/auth.asgardeo.tsx +import type { ActionFunctionArgs } from "@remix-run/node"; + +import { authenticator } from "~/utils/asgardeo.server"; + +export let loader = () => redirect("/login"); + +export let action = ({ request }: ActionFunctionArgs) => { + return authenticator.authenticate("asgardeo", request); +}; +``` + +```ts +// app/routes/auth.asgardeo.callback.tsx +import type { LoaderFunctionArgs } from "@remix-run/node"; + +import { authenticator } from "~/utils/asgardeo.server"; + +export let loader = ({ request }: LoaderFunctionArgs) => { + return authenticator.authenticate("asgardeo", request, { + successRedirect: "/dashboard", + failureRedirect: "/login", + }); +}; +``` + +```ts +// app/routes/auth.logout.ts +import type { ActionFunctionArgs } from "@remix-run/node"; + +import { redirect } from "@remix-run/node"; + +import { destroySession, getSession } from "~/utils/asgardeo.server"; + +export const action = async ({ request }: ActionFunctionArgs) => { + const session = await getSession(request.headers.get("Cookie")); + const logoutURL = new URL(process.env.ASGARDEO_LOGOUT_URL); // i.e https://api.asgardeo.io/t/pavinduorg/oidc/logout + + logoutURL.searchParams.set("client_id", process.env.ASGARDEO_CLIENT_ID); + logoutURL.searchParams.set("returnTo", process.env.ASGARDEO_RETURN_TO_URL); + + return redirect(logoutURL.toString(), { + headers: { + "Set-Cookie": await destroySession(session), + }, + }); +}; +``` + +## Contribute +Please read [Contributing Guide](CONTRIBUTING.md) for details on how to contribute to Remix Auth Asgardeo. Refer to [General Contribution Guidelines](http://wso2.github.io/) for details on our code of conduct, and the process for submitting pull requests to us. + +### Reporting issues +We encourage you to report issues, improvements, and feature requests creating [Github Issues](https://github.com/asgardeo/remix-auth-asgardeo/issues). + +**Important**: Please be advised that security issues MUST be reported to security@wso2com, not as GitHub issues, in order to reach the proper audience. We strongly advise following the WSO2 Security Vulnerability Reporting Guidelines when reporting the security issues. + +## License +This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details. diff --git a/lib/package.json b/lib/package.json index cc938ae..fcc194a 100644 --- a/lib/package.json +++ b/lib/package.json @@ -1,6 +1,6 @@ { "name": "@asgardeo/remix-auth-asgardeo", - "version": "0.0.1", + "version": "0.0.2", "description": "An Asgardeo Strategy for Remix Auth, based on the OAuth2Strategy", "author": "WSO2", "license": "Apache-2.0",