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

Various QOL changes. #169

Merged
merged 14 commits into from
Mar 20, 2024
20 changes: 10 additions & 10 deletions .github/workflows/pull_request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,37 +3,37 @@ jobs:
arrange:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-go@v2
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.16'
- run: go get github.com/jdeflander/goarrange
- run: go install github.com/jdeflander/goarrange@v1.0.0
working-directory: ${{ runner.temp }}
- run: test -z "$(goarrange run -r -d)"

lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: golangci/golangci-lint-action@v2
- uses: actions/checkout@v4
- uses: golangci/golangci-lint-action@v4
with:
version: v1.39
version: 'v1.56.2'
args: -E misspell,godot,whitespace

test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-go@v2
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.16'
- run: go test -v ./...

tidy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-go@v2
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.16'
- run: go mod tidy
Expand Down
21 changes: 21 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
.PHONY: all arrange tidy lint test
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the Makefile has been added, wouldn't using it in the Github workflow make sense? There is some code duplication now in both places.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is some duplication, the big difference is that in the CI it checks whether it has been done, and in the Makefile it is actually executing the actions.


all: arrange tidy lint test

arrange:
@echo "Arranging files..."
@go fmt ./...
@goarrange run -r

tidy:
@echo "Tidying up..."
@go mod tidy

lint:
q-uint marked this conversation as resolved.
Show resolved Hide resolved
@echo "Linting files..."
@go vet ./...
@golangci-lint run ./... -E misspell,godot,whitespace

test:
@echo "Running tests..."
@go test ./... -cover
71 changes: 61 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,45 +3,56 @@
[![GoVersion](https://img.shields.io/github/go-mod/go-version/elimity-com/scim.svg)](https://github.com/elimity-com/scim)
[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/elimity-com/scim)


[![Tag](https://img.shields.io/github/tag/elimity-com/scim.svg)](https://gitHub.com/elimity-com/scim/releases)

This is an open source implementation of the [SCIM v2.0](http://www.simplecloud.info/#Specification) specification for use in Golang.
This is an open source implementation of the [SCIM v2.0](http://www.simplecloud.info/#Specification) specification for
use in Golang.
SCIM defines a flexible schema mechanism and REST API for managing identity data.
The goal is to reduce the complexity of user management operations by providing patterns for exchanging schemas using HTTP.
The goal is to reduce the complexity of user management operations by providing patterns for exchanging schemas using
HTTP.

In this implementation it is easy to add *custom* schemas and extensions with the provided structures.
Incoming resources will be *validated* by their corresponding schemas before being passed on to their callbacks.

The following features are supported:

- GET for `/Schemas`, `/ServiceProviderConfig` and `/ResourceTypes`
- CRUD (POST/GET/PUT/DELETE and PATCH) for your own resource types (i.e. `/Users`, `/Groups`, `/Employees`, ...)

Other optional features such as sorting, bulk, etc. are **not** supported in this version.

## Installation

Assuming you already have a (recent) version of Go installed, you can get the code with go get:

```bash
$ go get github.com/elimity-com/scim
```

## Usage

**!** errors are ignored for simplicity.

### 1. Create a service provider configuration.

[RFC Config](https://tools.ietf.org/html/rfc7643#section-5) |
[Example Config](https://tools.ietf.org/html/rfc7643#section-8.5)

```go
config := scim.ServiceProviderConfig{
DocumentationURI: optional.NewString("www.example.com/scim"),
}
```

**!** no additional features/operations are supported in this version.

### 2. Create all supported schemas and extensions.

[RFC Schema](https://tools.ietf.org/html/rfc7643#section-2) |
[User Schema](https://tools.ietf.org/html/rfc7643#section-4.1) |
[Group Schema](https://tools.ietf.org/html/rfc7643#section-4.2) |
[Extension Schema](https://tools.ietf.org/html/rfc7643#section-4.3)

```go
schema := schema.Schema{
ID: "urn:ietf:params:scim:schemas:core:2.0:User",
Expand Down Expand Up @@ -72,18 +83,23 @@ extension := schema.Schema{
```

### 3. Create all resource types and their callbacks.

[RFC Resource Type](https://tools.ietf.org/html/rfc7643#section-6) |
[Example Resource Type](https://tools.ietf.org/html/rfc7643#section-8.6)

#### 3.1 Callback (implementation of `ResourceHandler`)

[Simple In Memory Example](resource_handler_test.go)

```go
var userResourceHandler scim.ResourceHandler
// initialize w/ own implementation
```

**!** each resource type should have its own resource handler.

#### 3.2 Resource Type

```go
resourceTypes := []ResourceType{
{
Expand All @@ -101,44 +117,79 @@ resourceTypes := []ResourceType{
```

### 4. Create Server

```go
server := Server{
Config: config,
serverArgs := &ServerArgs{
ServiceProviderConfig: config,
ResourceTypes: resourceTypes,
}

serverOpts := []ServerOption{
WithLogger(logger), // optional, default is no logging
}

server, err := NewServer(serverArgs, serverOpts...)
```

## Backwards Compatibility

Even though the SCIM package has been running in some production environments, it is still in an early stage, and not
all features are supported. So be aware that a change in the minor version could break your implementation. We will not
make any breaking changes that takes hours to fix, but some functions might change name or signature.

This was the case for `v0.1` to `v0.2.0`.

## String Values for Attributes

By default, the SCIM server will NOT use the `string` type for all attributes, since this is NOT compliant with the
SCIM specification. It is still possible to enable this behavior by toggling a flag within the `schema` package.

```go
import "github.com/elimity-com/scim/schema"

schema.SetAllowStringValues(true)
```

## Addition Checks/Tests

Not everything can be checked by the SCIM server itself.
Below are some things listed that we expect that the implementation covers.

**!** this list is currently incomplete!

We want to keep this list as short as possible.
We want to keep this list as short as possible.
If you have ideas how we could enforce these rules in the server itself do not hesitate to open
[an issue](https://github.com/elimity-com/scim/issues/new) or a PR.

### Mutability

#### Immutable Attributes

*PUT Handler*: If one or more values are already set for the attribute, the input value(s) MUST match.

#### WriteOnly Attributes

*ALL Handlers*: Attribute values SHALL NOT be returned. \
Note: These attributes usually also has a returned setting of "never".

## Contributing

[![Contributors](https://img.shields.io/github/contributors/elimity-com/scim.svg)](https://gitHub.com/elimity-com/scim/contributors/)

We are happy to review pull requests,
but please first discuss the change you wish to make via issue, email,
or any other method with the owners of this repository before making a change.

If you would like to propose a change please ensure the following:
- All checks of GitHub Actions are passing ([GolangCI-Lint](https://github.com/golangci/golangci-lint): `misspell`, `godot` and `whitespace`)

- All checks of GitHub Actions are
passing ([GolangCI-Lint](https://github.com/golangci/golangci-lint): `misspell`, `godot` and `whitespace`)
- All already existing tests are passing.
- You have written tests that cover the code you are making, make sure to include edge cases.
- There is documentation for at least all public functions you have added.
- New public functions and structures are kept to a minimum.
- The same practices are applied (such as the anatomy of methods, names, etc.)
- Your changes are compliant with SCIM v2.0 (released as
[RFC7642](https://tools.ietf.org/html/rfc7642),
[RFC7643](https://tools.ietf.org/html/rfc7643) and
[RFC7644](https://tools.ietf.org/html/rfc7644) under [IETF](https://ietf.org/)).
[RFC7642](https://tools.ietf.org/html/rfc7642),
[RFC7643](https://tools.ietf.org/html/rfc7643) and
[RFC7644](https://tools.ietf.org/html/rfc7644) under [IETF](https://ietf.org/)).
52 changes: 42 additions & 10 deletions examples_test.go
Original file line number Diff line number Diff line change
@@ -1,21 +1,53 @@
package scim

import (
"log"
logger "log"
"net/http"
)

func ExampleNewServer() {
log.Fatal(http.ListenAndServe(":7643", Server{
Config: ServiceProviderConfig{},
ResourceTypes: nil,
}))
args := &ServerArgs{
ServiceProviderConfig: &ServiceProviderConfig{},
ResourceTypes: []ResourceType{},
}
server, err := NewServer(args)
if err != nil {
logger.Fatal(err)
}
logger.Fatal(http.ListenAndServe(":7643", server))
}

func ExampleNewServer_basePath() {
http.Handle("/scim/", http.StripPrefix("/scim", Server{
Config: ServiceProviderConfig{},
ResourceTypes: nil,
}))
log.Fatal(http.ListenAndServe(":7643", nil))
args := &ServerArgs{
ServiceProviderConfig: &ServiceProviderConfig{},
ResourceTypes: []ResourceType{},
}
server, err := NewServer(args)
if err != nil {
logger.Fatal(err)
}
// You can host the SCIM server on a custom path, make sure to strip the prefix, so only `/v2/` is left.
http.Handle("/scim/", http.StripPrefix("/scim", server))
logger.Fatal(http.ListenAndServe(":7643", nil))
}

func ExampleNewServer_logger() {
q-uint marked this conversation as resolved.
Show resolved Hide resolved
loggingMiddleware := func(next http.Handler) http.Handler {
fn := func(w http.ResponseWriter, r *http.Request) {
logger.Println(r.Method, r.URL.Path)

next.ServeHTTP(w, r)
}

return http.HandlerFunc(fn)
}
args := &ServerArgs{
ServiceProviderConfig: &ServiceProviderConfig{},
ResourceTypes: []ResourceType{},
}
server, err := NewServer(args)
if err != nil {
logger.Fatal(err)
}
logger.Fatal(http.ListenAndServe(":7643", loggingMiddleware(server)))
}
File renamed without changes.
14 changes: 7 additions & 7 deletions internal/filter/filter_test.go → filter/filter_test.go
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package filter_test

import (
internal "github.com/elimity-com/scim/internal/filter"
"github.com/elimity-com/scim/filter"
"github.com/elimity-com/scim/schema"
"testing"
)
Expand All @@ -25,7 +25,7 @@ func TestPathValidator_Validate(t *testing.T) {
`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber`,
`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.displayName`,
} {
validator, err := internal.NewPathValidator(f, schema.CoreUserSchema(), schema.ExtensionEnterpriseUser())
validator, err := filter.NewPathValidator(f, schema.CoreUserSchema(), schema.ExtensionEnterpriseUser())
if err != nil {
t.Fatal(err)
}
Expand All @@ -47,7 +47,7 @@ func TestPathValidator_Validate(t *testing.T) {
`urn:ietf:params:scim:schemas:core:2.0:User:employeeNumber`,
`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:userName`,
} {
validator, err := internal.NewPathValidator(f, schema.CoreUserSchema(), schema.ExtensionEnterpriseUser())
validator, err := filter.NewPathValidator(f, schema.CoreUserSchema(), schema.ExtensionEnterpriseUser())
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -92,7 +92,7 @@ func TestValidator_PassesFilter(t *testing.T) {
},
},
} {
validator, err := internal.NewValidator(test.filter, schema.CoreUserSchema())
validator, err := filter.NewValidator(test.filter, schema.CoreUserSchema())
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -137,7 +137,7 @@ func TestValidator_PassesFilter(t *testing.T) {
userSchema := schema.CoreUserSchema()
userSchema.Attributes = append(userSchema.Attributes, schema.SchemasAttributes())
userSchema.Attributes = append(userSchema.Attributes, schema.CommonAttributes()...)
validator, err := internal.NewValidator(test.filter, userSchema)
validator, err := filter.NewValidator(test.filter, userSchema)
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -168,7 +168,7 @@ func TestValidator_PassesFilter(t *testing.T) {
filter: `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization eq "Elimity"`,
},
} {
validator, err := internal.NewValidator(test.filter, schema.ExtensionEnterpriseUser())
validator, err := filter.NewValidator(test.filter, schema.ExtensionEnterpriseUser())
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -212,7 +212,7 @@ func TestValidator_Validate(t *testing.T) {
`userType eq "Employee" and emails[type eq "work" and value co "@example.com"]`,
`emails[type eq "work" and value co "@example.com"] or ims[type eq "xmpp" and value co "@foo.com"]`,
} {
validator, err := internal.NewValidator(f, userSchema)
validator, err := filter.NewValidator(f, userSchema)
if err != nil {
t.Fatal(err)
}
Expand Down
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ package filter_test

import (
"fmt"
internal "github.com/elimity-com/scim/internal/filter"
internal "github.com/elimity-com/scim/filter"
"github.com/elimity-com/scim/schema"
"github.com/scim2/filter-parser/v2"
"testing"
Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ package filter_test

import (
"fmt"
internal "github.com/elimity-com/scim/internal/filter"
internal "github.com/elimity-com/scim/filter"
"github.com/elimity-com/scim/schema"
"github.com/scim2/filter-parser/v2"
"testing"
Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ package filter_test

import (
"fmt"
internal "github.com/elimity-com/scim/internal/filter"
internal "github.com/elimity-com/scim/filter"
"github.com/elimity-com/scim/schema"
"github.com/scim2/filter-parser/v2"
"testing"
Expand Down
File renamed without changes.
Loading