{"id":15639667,"url":"https://github.com/manicminer/hamilton","last_synced_at":"2025-05-15T16:09:49.640Z","repository":{"id":39578163,"uuid":"289590894","full_name":"manicminer/hamilton","owner":"manicminer","description":"Go SDK for Microsoft Graph","archived":false,"fork":false,"pushed_at":"2024-09-24T22:42:30.000Z","size":1641,"stargazers_count":87,"open_issues_count":15,"forks_count":62,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-12T14:54:44.537Z","etag":null,"topics":["go","golang","microsoft-graph","ms-graph"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/manicminer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2020-08-23T00:47:34.000Z","updated_at":"2025-03-15T23:21:04.000Z","dependencies_parsed_at":"2023-09-26T00:52:19.245Z","dependency_job_id":"6ae16705-3435-4795-b893-8026fb84a4fe","html_url":"https://github.com/manicminer/hamilton","commit_stats":null,"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manicminer%2Fhamilton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manicminer%2Fhamilton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manicminer%2Fhamilton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manicminer%2Fhamilton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manicminer","download_url":"https://codeload.github.com/manicminer/hamilton/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374485,"owners_count":22060612,"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":["go","golang","microsoft-graph","ms-graph"],"created_at":"2024-10-03T11:26:54.597Z","updated_at":"2025-05-15T16:09:49.602Z","avatar_url":"https://github.com/manicminer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚠️ This project is now deprecated\n\n**Please refer to the [Microsoft Graph SDK](https://github.com/hashicorp/go-azure-sdk/tree/main/microsoft-graph) published by HashiCorp, for a comprehensive replacement to this SDK**\n\n\u003cbr\u003e\n\n---\n\n\u003cbr\u003e\n\n# Hamilton is a Go SDK for Microsoft Graph\n\nThis is a working Go client for the [Microsoft Graph API][ms-graph-docs]. It is actively maintained and has growing\nsupport for services and objects in Azure Active Directory.\n\n## Documentation\n\nSee [pkg.go.dev](https://pkg.go.dev/github.com/manicminer/hamilton).\n\n## Features\n\n- Automatic retries for failed requests and handling of eventual consistency on writes due to propagation delays\n- Automatic paging of results\n- Native model structs for marshaling and unmarshaling\n- Support for national clouds including US Government (L4 and L5) and China\n- Support for both the v1.0 and beta API endpoints\n- Ability to inject middleware functions for logging etc\n- OData parsing in API responses and support for OData queries such as filters, sorting, searching, expand and select\n- Authentication now uses [github.com/hashicorp/go-azure-sdk/sdk/auth](https://github.com/hashicorp/go-azure-sdk/tree/main/sdk/auth)\n\n## Getting Started\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\t\"github.com/hashicorp/go-azure-sdk/sdk/auth\"\n\t\"github.com/hashicorp/go-azure-sdk/sdk/environments\"\n\t\"github.com/hashicorp/go-azure-sdk/sdk/odata\"\n\t\"github.com/manicminer/hamilton/msgraph\"\n)\n\nvar (\n\ttenantId     = os.Getenv(\"TENANT_ID\")\n\tclientId     = os.Getenv(\"CLIENT_ID\")\n\tclientSecret = os.Getenv(\"CLIENT_SECRET\")\n)\n\nfunc main() {\n\tctx := context.Background()\n\tenv := environments.AzurePublic()\n\n\tcredentials := auth.Credentials{\n\t\tEnvironment:  *env,\n\t\tTenantID:     tenantId,\n\t\tClientID:     clientId,\n\t\tClientSecret: clientSecret,\n\n\t\tEnableAuthenticatingUsingClientSecret: true,\n\t}\n\n\tauthorizer, err := auth.NewAuthorizerFromCredentials(ctx, credentials, env.MicrosoftGraph)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tclient := msgraph.NewUsersClient()\n\tclient.BaseClient.Authorizer = authorizer\n\n\tusers, _, err := client.List(ctx, odata.Query{})\n\tif err != nil {\n\t\tlog.Println(err)\n\t\treturn\n\t}\n\tif users == nil {\n\t\tlog.Println(\"bad API response, nil result received\")\n\t\treturn\n\t}\n\tfor _, user := range *users {\n\t\tfmt.Printf(\"%s: %s \u003c%s\u003e\\n\", *user.ID(), *user.DisplayName, *user.UserPrincipalName)\n\t}\n}\n```\n\n## Configure retry limit for all failed requests\n\n```go\nclient := msgraph.NewUsersClient(tenantId)\nclient.BaseClient.Authorizer = authorizer\nclient.BaseClient.RetryableClient.RetryMax = 8\n```\n\n## Disable eventual consistency handling\n\n_Note: this does **not** disable auto-retries for failed requests (e.g. HTTP 429 or 500 responses)_\n\n```go\nclient := msgraph.NewUsersClient(tenantId)\nclient.BaseClient.Authorizer = authorizer\nclient.BaseClient.DisableRetries = true\n```\n\n## Log requests and responses\n\n```go\nrequestLogger := func(req *http.Request) (*http.Request, error) {\n\tif req != nil {\n\t\tif dump, err := httputil.DumpRequestOut(req, true); err == nil {\n\t\t\tlog.Printf(\"%s\\n\", dump)\n\t\t}\n\t}\n\treturn req, nil\n}\n\nresponseLogger := func(req *http.Request, resp *http.Response) (*http.Response, error) {\n\tif resp != nil {\n\t\tif dump, err := httputil.DumpResponse(resp, true); err == nil {\n\t\t\tlog.Printf(\"%s\\n\", dump)\n\t\t}\n\t}\n\treturn resp, nil\n}\n\nclient := msgraph.NewUsersClient(tenantId)\nclient.BaseClient.Authorizer = authorizer\nclient.BaseClient.DisableRetries = true\nclient.BaseClient.RequestMiddlewares = \u0026[]msgraph.RequestMiddleware{requestLogger}\nclient.BaseClient.ResponseMiddlewares = \u0026[]msgraph.ResponseMiddleware{responseLogger}\n```\n\n## Contributing\n\nContributions are welcomed! Please note that clients must have tests that cover all methods where feasible.\n\nPlease raise a pull request [on GitHub][gh-project] to submit contributions. Bug reports and feature requests are happily received.\n\n## Testing\n\nTesting requires at least one Azure AD tenant and real credentials.\n\nNote that running all tests requires three separate tenants, and that some tests require an Azure AD Premium P2 license and/or an Office 365 license.\n\n\u003e ℹ️ You can sign up for the [Microsoft 365 Developer Program](https://developer.microsoft.com/en-us/microsoft-365/dev-program) which offers a Microsoft 365 E5 subscription for 25 users, at no cost for development purposes. That will suffice for most tests.\n\nIt's recommended to use an isolated tenant for testing and _not_ a production tenant.\n\nYou can authenticate with any supported method for the client tests, and the auth tests are split by authentication method.\n\nNote that each client generally has a single test that exercises all methods. This is to help ensure that test objects\nare cleaned up where possible. Where tests fail, often objects will be left behind and should be cleaned up separately.\nThe [test-cleanup](https://github.com/manicminer/hamilton/tree/main/internal/cmd/test-cleanup) command can be used to\ndelete leftover test objects in the event of test failure.\n\n### Configuring single-tenant tests (eg. with a no-cost subscription from Microsoft 365 Developer Program)\nTo set up environment variables:\n```shell\naz login --allow-no-subscriptions\n\n# create one in the Azure Portal -\u003e Entra ID -\u003e App registrations -\u003e New Registration\n# set \"hamilton\" as name, accept other defaults. Then copy Essentials -\u003e Application (client) ID\nexport CLIENT_ID=...\n# find this on the Azure Portal -\u003e Entra ID -\u003e Basic Information -\u003e Tenant ID\nexport TENANT_ID=...\n# find this on the Azure Portal -\u003e Entra ID -\u003e Basic Information -\u003e Primary domain\nexport TENANT_DOMAIN=...\n\nexport DEFAULT_TENANT_ID=${TENANT_ID}\nexport DEFAULT_TENANT_DOMAIN=${TENANT_DOMAIN}\nexport CONNECTED_TENANT_ID=${TENANT_ID}\nexport CONNECTED_TENANT_DOMAIN=${TENANT_DOMAIN}\nexport B2C_TENANT_ID=${TENANT_ID}\nexport B2C_TENANT_DOMAIN=${TENANT_DOMAIN}\n```\n\nTo run one test (eg. `TestUsersClient`):\n```shell\ngo test --race '-run=^TestUsersClient$' ./...\n```\n\n\n### Configuring and running all tests\nTo set up environment variables:\n```shell\naz login\n\n# find this on the Azure Portal -\u003e Entra ID -\u003e Basic Information -\u003e Tenant ID\nexport DEFAULT_TENANT_ID=...\n# find this on the Azure Portal -\u003e Entra ID -\u003e Basic Information -\u003e Primary domain\nexport DEFAULT_TENANT_DOMAIN=...\n\n# same as above, but from a separate tenant, to run TestConnectedOrganizationClient\nexport CONNECTED_TENANT_ID=...\nexport CONNECTED_TENANT_DOMAIN=${TENANT_DOMAIN}\n\n# same as above, but from yet another separate tenant, to run TestB2CUserFlowClient\nexport B2C_TENANT_ID=${TENANT_ID}\nexport B2C_TENANT_DOMAIN=${TENANT_DOMAIN}\n```\n\n\u003e ℹ️ View all supported environment variables in the [`envDefault()` testing helper function](https://github.com/manicminer/hamilton/blob/main/internal/test/testing.go).\n\nTo run all the tests:\n```shell\n$ make test\n```\n\n\n[gh-project]: https://github.com/manicminer/hamilton\n[ms-graph-docs]: https://docs.microsoft.com/en-us/graph/overview\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanicminer%2Fhamilton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanicminer%2Fhamilton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanicminer%2Fhamilton/lists"}