{"id":13504996,"url":"https://github.com/vapor-community/Imperial","last_synced_at":"2025-03-29T22:31:23.496Z","repository":{"id":37821170,"uuid":"110582331","full_name":"vapor-community/Imperial","owner":"vapor-community","description":"Federated Authentication with OAuth providers","archived":false,"fork":false,"pushed_at":"2025-01-01T22:12:26.000Z","size":3923,"stargazers_count":163,"open_issues_count":15,"forks_count":51,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-27T17:16:52.285Z","etag":null,"topics":["federated-identity","federated-social-web","hacktoberfest","imperial","oauth","spm","swift","swift-package-manager","swift4","vapor","vapor-3","vapor-4","vapor-provider"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vapor-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-13T17:58:51.000Z","updated_at":"2025-03-17T02:50:44.000Z","dependencies_parsed_at":"2022-08-19T11:20:59.893Z","dependency_job_id":"11f12e73-3b89-47fb-9b0c-a83359aff180","html_url":"https://github.com/vapor-community/Imperial","commit_stats":{"total_commits":351,"total_committers":24,"mean_commits":14.625,"dds":"0.31908831908831914","last_synced_commit":"c12fc31991ab56f4e5582bc10e5872fa328b9beb"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vapor-community%2FImperial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vapor-community%2FImperial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vapor-community%2FImperial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vapor-community%2FImperial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vapor-community","download_url":"https://codeload.github.com/vapor-community/Imperial/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246254077,"owners_count":20747946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["federated-identity","federated-social-web","hacktoberfest","imperial","oauth","spm","swift","swift-package-manager","swift4","vapor","vapor-3","vapor-4","vapor-provider"],"created_at":"2024-08-01T00:00:56.495Z","updated_at":"2025-03-29T22:31:23.460Z","avatar_url":"https://github.com/vapor-community.png","language":"Swift","funding_links":[],"categories":["Packages","Authentication","Swift"],"sub_categories":["Authentication"],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://avatars.githubusercontent.com/u/26165732?s=200\u0026v=4\" width=\"100\" height=\"100\" alt=\"avatar\" /\u003e\n    \u003ch1\u003eImperial\u003c/h1\u003e\n    \u003ca href=\"https://swiftpackageindex.com/vapor-community/Imperial/documentation\"\u003e\n        \u003cimg src=\"https://design.vapor.codes/images/readthedocs.svg\" alt=\"Documentation\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://discord.gg/vapor\"\u003e\u003cimg src=\"https://design.vapor.codes/images/discordchat.svg\" alt=\"Team Chat\"\u003e\u003c/a\u003e\n    \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://design.vapor.codes/images/mitlicense.svg\" alt=\"MIT License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/vapor-community/Imperial/actions/workflows/test.yml\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/vapor-community/Imperial/test.yml?event=push\u0026style=plastic\u0026logo=github\u0026label=tests\u0026logoColor=%23ccc\" alt=\"Continuous Integration\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://codecov.io/github/vapor-community/Imperial\"\u003e\n        \u003cimg src=\"https://img.shields.io/codecov/c/github/vapor-community/Imperial?style=plastic\u0026logo=codecov\u0026label=codecov\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://swift.org\"\u003e\n        \u003cimg src=\"https://design.vapor.codes/images/swift60up.svg\" alt=\"Swift 6.0+\"\u003e\n    \u003c/a\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n🔐 Federated Authentication with OAuth providers for Vapor.\n\n### Installation\n\nUse the SPM string to easily include the dependendency in your `Package.swift` file\n\n```swift\n.package(url: \"https://github.com/vapor-community/Imperial.git\", from: \"2.0.0-beta.2\")\n```\n\nand then add the desired provider to your target's dependencies:\n\n```swift\n.product(name: \"ImperialGitHub\", package: \"imperial\")\n```\n\n## Overview\n\nImperial is a Federated Login service, allowing you to easily integrate your Vapor applications with OAuth providers to handle your apps authentication.\n\n## Getting Started\n\n### Sessions Middleware\n\nImperial relies on the [sessions middleware](https://docs.vapor.codes/4.0/sessions/#configuration) to save state and access tokens. In **configure.swift**, or as a route group for specific routes, add the sessions middleware. For example, to add it globally:\n\n```swift\napp.middleware.use(app.sessions.middleware)\n```\n\n### Route Registration\n\nImperial uses environment variables to access the client ID and secret to authenticate with the provider. See the provider specific docs for details on what they should be.\n\nYou need to register the OAuth service with your route. For example, to register a GitHub integration add the following:\n\n```swift\ntry routes.oAuth(from: GitHub.self, authenticate: \"github\", callback: \"gh-auth-complete\") { req, token in\n    print(token)\n    return req.redirect(to: \"/\")\n}\n```\n\nThis registers a route to `/github`. When you visit that route, Imperial will trigger the OAuth flow using the `GitHub` service. The callback path is the one registered with the OAuth provider when you create your application. The completion handler is fired when the callback route is called by the OAuth provider. The access token is passed in and a response is returned.\n\nIf you just want to redirect, without doing anything else in the callback, you can use the helper ``RoutesBuilder/oAuth(from:authenticate:authenticateCallback:callback:scope:redirect:)`` method that takes in a redirect string:\n\n```swift\ntry router.oAuth(from: GitHub.self, authenticate: \"github\", callback: \"gh-auth-complete\", redirect: \"/\")\n```\n\n### Access Tokens and Middleware\n\nIf you ever want to get the `access_token` in a route, you can use a helper method for the `Request` type that comes with Imperial:\n\n```swift\nlet token = try request.accessToken\n```\n\nNow that you are authenticating the user, you will want to protect certain routes to make sure the user is authenticated. You can do this by adding the ``ImperialMiddleware`` to a router group (or maybe your middleware config):\n\n```swift\nlet protected = routes.grouped(ImperialMiddleware())\n```\n\nThen, add your protected routes to the `protected` group:\n\n```swift\nprotected.get(\"me\", use: me)\n```\n\nThe ``ImperialMiddleware`` by default passes the errors it finds onto `ErrorMiddleware` where they are caught, but you can initialize it with a redirect path to go to if the user is not authenticated:\n\n```swift\nlet protected = routes.grouped(ImperialMiddleware(redirect: \"/\"))\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvapor-community%2FImperial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvapor-community%2FImperial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvapor-community%2FImperial/lists"}