001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.scim; 018 019import com.google.errorprone.annotations.CheckReturnValue; 020import org.jspecify.annotations.NonNull; 021import org.jspecify.annotations.Nullable; 022import javax.annotation.concurrent.Immutable; 023import javax.annotation.concurrent.NotThreadSafe; 024import java.net.URI; 025import java.util.Objects; 026import java.util.Optional; 027import java.util.Set; 028 029/** 030 * Immutable description of an application authentication scheme; it performs no authentication. 031 * Specification and documentation links are trusted bounded HTTP(S) URIs and are never fetched. 032 * @since 1.0.0 033 */ 034@Immutable 035@CheckReturnValue 036public final class ScimAuthenticationScheme { 037 private final @NonNull String type; 038 private final @NonNull String name; 039 private final @NonNull String description; 040 private final boolean primary; 041 private final @Nullable URI specUri; 042 private final @Nullable URI documentationUri; 043 044 private ScimAuthenticationScheme(@NonNull Builder builder) { 045 if (builder.name == null || builder.description == null) 046 throw new IllegalStateException("A SCIM authentication scheme requires name and description."); 047 type = builder.type; 048 name = builder.name; 049 description = builder.description; 050 primary = Boolean.TRUE.equals(builder.primary); 051 specUri = builder.specUri; 052 documentationUri = builder.documentationUri; 053 } 054 055 /** 056 * Starts a standard authentication scheme with its exact SCIM type spelling. 057 * @param type oauth, oauth2, oauthbearertoken, httpbasic or httpdigest 058 * @return a new builder 059 * @since 1.0.0 060 */ 061 public static @NonNull Builder withType(@NonNull String type) { 062 ScimSchemas.requireName(Objects.requireNonNull(type)); 063 if (!Set.of("oauth", "oauth2", "oauthbearertoken", "httpbasic", "httpdigest").contains(type)) 064 throw new IllegalArgumentException("Unsupported standard SCIM authentication scheme type."); 065 return new Builder(type); 066 } 067 068 /** 069 * Returns the exact standard scheme type. 070 * @return the exact standard scheme type 071 * @since 1.0.0 072 */ 073 public @NonNull String getType() { return type; } 074 075 /** 076 * Returns the human-readable scheme name. 077 * @return the human-readable scheme name 078 * @since 1.0.0 079 */ 080 public @NonNull String getName() { return name; } 081 082 /** 083 * Returns the scheme description. 084 * @return the scheme description 085 * @since 1.0.0 086 */ 087 public @NonNull String getDescription() { return description; } 088 089 /** 090 * Returns whether this is the preferred scheme. 091 * @return whether this is the preferred scheme 092 * @since 1.0.0 093 */ 094 public @NonNull Boolean isPrimary() { return primary; } 095 096 /** 097 * Returns the optional specification URI. 098 * @return the optional specification URI 099 * @since 1.0.0 100 */ 101 public @NonNull Optional<@NonNull URI> getSpecUri() { return Optional.ofNullable(specUri); } 102 103 /** 104 * Returns the optional documentation URI. 105 * @return the optional documentation URI 106 * @since 1.0.0 107 */ 108 public @NonNull Optional<@NonNull URI> getDocumentationUri() { return Optional.ofNullable(documentationUri); } 109 110 /** 111 * Compares all scheme description characteristics. 112 * @param other the comparison value 113 * @return whether descriptions are equal 114 * @since 1.0.0 115 */ 116 @Override public boolean equals(@Nullable Object other) { 117 return this == other || (other instanceof ScimAuthenticationScheme value && primary == value.primary 118 && type.equals(value.type) && name.equals(value.name) && description.equals(value.description) 119 && Objects.equals(specUri, value.specUri) && Objects.equals(documentationUri, value.documentationUri)); 120 } 121 122 /** 123 * Returns the scheme description hash. 124 * @return the description hash 125 * @since 1.0.0 126 */ 127 @Override public int hashCode() { return Objects.hash(type, name, description, primary, specUri, documentationUri); } 128 129 /** 130 * Returns a fixed redacted description. 131 * @return a fixed redacted description 132 * @since 1.0.0 133 */ 134 @Override public @NonNull String toString() { return "ScimAuthenticationScheme{<redacted>}"; } 135 136 /** 137 * Mutable, non-thread-safe authentication-scheme description configuration. 138 * @since 1.0.0 139 */ 140 @NotThreadSafe 141 @CheckReturnValue 142 public static final class Builder { 143 private final @NonNull String type; 144 private @Nullable String name; 145 private @Nullable String description; 146 private @Nullable Boolean primary; 147 private @Nullable URI specUri; 148 private @Nullable URI documentationUri; 149 private Builder(@NonNull String type) { this.type = type; } 150 151 /** 152 * Sets name; null restores unset. 153 * @param value the setting, or null to restore its default 154 * @return this builder 155 * @since 1.0.0 156 */ 157 public @NonNull Builder name(@Nullable String value) { name = value == null ? null : ScimSchemas.requireName(value); return this; } 158 159 /** 160 * Sets description; null restores unset. 161 * @param value the setting, or null to restore its default 162 * @return this builder 163 * @since 1.0.0 164 */ 165 public @NonNull Builder description(@Nullable String value) { description = value == null ? null : ScimSchemas.requireText(value, true); return this; } 166 167 /** 168 * Sets primary; null restores false. 169 * @param value the setting, or null to restore its default 170 * @return this builder 171 * @since 1.0.0 172 */ 173 public @NonNull Builder primary(@Nullable Boolean value) { primary = value; return this; } 174 175 /** 176 * Sets specUri; null restores absent. 177 * @param value the setting, or null to restore its default 178 * @return this builder 179 * @since 1.0.0 180 */ 181 public @NonNull Builder specUri(@Nullable URI value) { specUri = value == null ? null : ScimSchemas.requireDocumentationUri(value); return this; } 182 183 /** 184 * Sets documentationUri; null restores absent. 185 * @param value the setting, or null to restore its default 186 * @return this builder 187 * @since 1.0.0 188 */ 189 public @NonNull Builder documentationUri(@Nullable URI value) { documentationUri = value == null ? null : ScimSchemas.requireDocumentationUri(value); return this; } 190 191 /** 192 * Validates required descriptions and creates an immutable scheme. 193 * @return the authentication-scheme description 194 * @since 1.0.0 195 */ 196 public @NonNull ScimAuthenticationScheme build() { return new ScimAuthenticationScheme(this); } 197 } 198}