https://github.com/sersoft-gmbh/auth-scope
A swift library to deal with authentication scopes
https://github.com/sersoft-gmbh/auth-scope
auth oauth scope swift
Last synced: 7 months ago
JSON representation
A swift library to deal with authentication scopes
- Host: GitHub
- URL: https://github.com/sersoft-gmbh/auth-scope
- Owner: sersoft-gmbh
- License: apache-2.0
- Created: 2019-07-26T17:49:40.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-09-18T14:29:16.000Z (over 1 year ago)
- Last Synced: 2024-11-17T17:35:51.048Z (about 1 year ago)
- Topics: auth, oauth, scope, swift
- Language: Swift
- Homepage: https://sersoft-gmbh.github.io/auth-scope/
- Size: 2.06 MB
- Stars: 0
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# AuthScope
[](https://github.com/sersoft-gmbh/auth-scope/releases/latest)
[](https://www.codacy.com/gh/sersoft-gmbh/auth-scope/dashboard?utm_source=github.com&utm_medium=referral&utm_content=sersoft-gmbh/auth-scope&utm_campaign=Badge_Grade)
[](https://codecov.io/gh/sersoft-gmbh/auth-scope)
[](https://sersoft-gmbh.github.io/auth-scope)
Handle authentication scopes with ease.
## Installation
### Swift Package Manager
Add the following package dependency to your `Package.swift`:
```swift
.package(url: "https://github.com/sersoft-gmbh/auth-scope", from: "4.0.0"),
```
## Usage
The main object you want to use is `Scope`. It's generic and wraps all the logic around a given `AccessRange` type. Since `Scope` can't know what access ranges you have, you need to provide them yourself. Typically, this is done by using an `enum` and conforming it to `AccessRangeProtocol`:
```swift
enum MyAccessRange: String, AccessRangeProtocol, CaseIterable {
case readPosts = "posts:read"
case writePosts = "posts:write"
case readUsers = "users:read"
case writeUsers = "users:write"
}
```
You can then use your `enum` with `Scope`:
```swift
let postsScope = Scope(accessRanges: .readPosts, .writePosts)
postsScope.contains(.writePosts) // -> true
postsScope.contains(.readUsers) // -> false
```
`Scope` conforms to `SetAlgebra` to make checking access ranges easier:
```swift
let completeScope = Scope.all // `.all` is available when `AccessRange` conforms to `CaseIterable`
completeScope.isSuperset(of: postsScope) // -> true
```
`Scope` is also able to generate a "scope string", since this is usually how they're provided to APIs. The "scope string" contains all access ranges (their `rawValue` to be exact) separated by space. It's important to note that `Scope` does not keep the access ranges in a given order. This means, that it's not guaranteed that two calls to `scopeString` will contain the access ranges in the same order. It is guaranteed, however, that the resulting scope contains all access ranges. `Scope` can of course also be created from a scope string. This initializer will throw an error if any of the contained access ranges is not valid.
```swift
let usersScope: Scope = [.readUsers, .writeUsers]
let string = usersScope.scopeString // -> "users:read users:write" OR "users:write users:read"
let recreatedScope = try Scope(scopeString: string)
usersScope == recreatedScope // true
```
`Scope` is also `Codable` and encodes/decodes itself as its scope string.
Last but not least, `Scope` also provides some useful regular expression patterns, that can be used to perform matches on a string basis. This is not recommended if your scopes are available as Swift types, but can be useful if you have to match scopes e.g. in a database.
There are currently three regular expression patterns that are provided:
- `exactMatchRegexPattern`: Returns a pattern that matches a scope string that contains **exactly** the same access ranges. Not more and not less.
- `containsAllRegexPattern`: Returns a pattern that matches a scope string that contains **all** access ranges, but is allowed to contain more.
- `containsAnyRegexPattern`: Returns a pattern that matches a scope string that contains **any** access ranges. A match is made as soon as one access range is contained.
For all these patterns, a `Regex` is available as well.
## Documentation
The API is documented using header doc. If you prefer to view the documentation as a webpage, there is an [online version](https://sersoft-gmbh.github.io/auth-scope) available for you.
## Contributing
If you find a bug / like to see a new feature in AuthScope there are a few ways of helping out:
- If you can fix the bug / implement the feature yourself please do and open a PR.
- If you know how to code (which you probably do), please add a (failing) test and open a PR. We'll try to get your test green ASAP.
- If you can do neither, then open an issue. While this might be the easiest way, it will likely take the longest for the bug to be fixed / feature to be implemented.
## License
See [LICENSE](./LICENSE) file.